Seda postitust toimetas viimati QWERTYU 2019-04-12 kell 14:24
SissejuhatusPärast asp.net Core'i kasutamist API arenduseks peab API dokumentatsiooni kirjutamine olema programmeerijatele valus ülesanne, kuid dokumentatsioon peab olema kirjutatud ning kui dokumentatsiooni formaadile pole konkreetseid nõudeid, sõltub lõplik dokumentatsioon täielikult arendaja meeleolust. Või olla detailsem või lihtsam. Kas on olemas kiire ja tõhus viis API dokumentatsiooni loomiseks? Vastus on jah, Swagger on üks populaarsemaid REST API-de dokumentatsiooni genereerimise tööriistu!
Miks kasutada Swaggerit REST API-de dokumentatsiooni genereerimise tööriistana- Swagger suudab luua interaktiivse API konsooli, mida arendajad saavad kasutada API-de kiireks õppimiseks ja katsetamiseks.
- Swagger suudab genereerida kliendi SDK-koodi rakendusteks erinevatel platvormidel.
- Swaggeri faile saab automaatselt genereerida koodikommentaaridest paljudel erinevatel platvormidel.
- Swaggeril on tugev kogukond paljude tugevate panustajatega.
Kuidas kasutada Swaggerit API dokumentatsiooni genereerimiseks asp.net tuumas?- Swashbuckle.AspNetCore on avatud lähtekoodiga projekt, mis genereerib Swaggeri dokumentatsiooni ASP.NET Core Web API jaoks.
- NSwag on veel üks avatud lähtekoodiga projekt, mis integreerib Swagger UI või ReDoci ASP.NET Core Web API-desse. See võimaldab genereerida C# ja TypeScript kliendikoodi API-dele.
Järgmine on näide Swashbuckle.AspNetCore'istMillised on Swashbuckle'i komponendid?- Swashbuckle.AspNetCore.Swagger: Avab SwaggerDocument objekti kui Swagger-objekti mudeli ja JSON-i lõpp-punktide vahetarkvara.
- Swashbuckle.AspNetCore.SwaggerGen: Swagger-generaator, mis genereerib SwaggerDocument objekte otse marsruutidest, kontrolleritest ja mudelitest. Seda kombineeritakse sageli Swagger endpoint middleware'iga, et automaatselt paljastada Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Swagger UI tööriista manustatud versioon. See tõlgendab Swagger JSON-i, et luua kohandatavaid ja rikkalikke kogemusi, mis kirjeldavad veebipõhiste API-de funktsionaalsust. See sisaldab sisseehitatud testimisvahendeid levinud meetodite jaoks.
Kuidas paigaldada Swashbuckle vs2017-ga?
Esimene viis: installi Package Manager Console'i aknast
- Mine vaadete > teiste Windows > Package Manager Console'i juurde
- Navigeeri kausta, mis sisaldab TodoApi.csproj faili
- Palun täida järgmine käsk · Install-Package Swashbuckle.AspNetCore
-
Teine viis: Halda NuGet pakette dialoogist:- Tee projektile paremklõps lahenduste halduris > halda NuGet pakette
- Sea paketi lähtekoodiks nuget.org
- Sisesta otsingukasti "Swashbuckle.AspNetCore"
- Vali Sirvimise vahekaardilt Swashbuckle.AspNetCore pakett ja klõpsa Installi
-
Lisa ja seadista Swagger middlewareTutvusta esmalt nimeruumi: Lisa Swaggeri generaator teenuste kogumisse Startup.ConfigureServices meetodis: juuresStartup.Configuremeetodit, võimaldades vahendustarkvara teenindada genereeritud JSON-dokumenti ja Swagger UI-d:
Käivita rakendus ja navigeeri sinnahttps://localhost:<port>/swagger/v1/swagger.json。 Tulemuseks olev dokumentatsioon, mis kirjeldab lõpp-punkti, kuvatakse JSON-formaadis järgmiselt.
Saadavalhttps://localhost:<port>/uhkusLeia Swaggeri kasutajaliides. Sirvi API dokumentatsiooni Swaggeri kasutajaliidese kaudu, nagu allpool näidatud.
Juure rakendamiseks (http://localhost:<port>/) Swagger kasutajaliides pakkumiseks palun sisestaMarsruudiprefiksOmadus on seatud tühjaks stringiks:
Swaggeri edasijõudnud kasutamine (kohandamine ja laiendused)Kasuta Swaggerit, et lisada API dokumentatsiooni selgitavat infotJärgmised konfiguratsioonitoimingud tehakse AddSwaggerGen meetodis, mis lisab teavet nagu autori, litsentsi ja kirjelduse info: Waggeri kasutajaliidese kuvaversiooni info on näidatud järgmisel joonisel: Lisa kommentaarid liidese meetoditeleKlikkime esmalt API-l, laiendame seda nagu alloleval joonisel näidatud – kas kommentaare ei tohi olla, kuidas kommentaare lisada? Lisa dokumendi kommentaarid, kus alloleval pildil on näidatud kolm/as, nagu allpool näidatud Seejärel käivita projekt ja mine tagasi swaggerUI-sse, et näha, kas kommentaar ilmub Ikka pole ilmunud, ära muretse, vaata alla! Luba XML-annotatsioonidXML-annotatsioone saab lubada järgmiste meetoditega: - Paremklõpsa projektile lahenduste halduris ja vali omadused
- Vaata XML dokumendifaili kasti Build vahekaardi väljundi all
-
XML-annotatsioonide lubamine annab silumisteavet dokumenteerimata tavaliste tüüpide ja liikmete kohta. Kui ilmub palju hoiatussõnumeid, näiteks viitab järgmine teade hoiatuskoodi 1591 rikkumisele:
Mis siis, kui sul on OCD ja tahad hoiatuse tühistada? Saad tühistada, nagu alloleval pildil näidatud
Pane tähele eelpool genereeritud xml-dokumendifaili teed,
Märkus: 1. Linuxi või mitte-Windowsi operatsioonisüsteemide puhul on failinimed ja -teed tähevülitundlikud. Näiteks töötab "SwaggerDemo.xml" fail Windowsis, aga mitte CentOS-is. 2. Rakendustee saamiseks soovitatakse kasutada AppContext.BaseDirectory selle saamiseks Ehita projekt uuesti üles ja käivita, et näha, kas kommentaarid ilmuvad Ülaltoodud operatsioonist võib kokku võtta, et Swagger kasutajaliides kuvab <summary> ülaltoodud kommentaarikoodi elementide sisemist teksti API suurte kommentaaridena! Muidugi võid lisada märkuste elemendi ka "Get how-to" dokumentatsiooni. See võib <summary> täiendada elemendis määratud infot ja pakkuda usaldusväärsemat Swaggeri kasutajaliidest. <remarks> Elementide sisu võib sisaldada teksti, JSON-i või XML-i. Kood on järgmine: Testi API liidest SwaggerUI abilSilume liidest SwaggerUI kaudu väikese näite kaudu
- Klõpsa API liidesel, mida tuleb testida, ja seejärel vajuta parameetrite vasakul ja paremal olevale nupule "Proovi välja"
- Sisesta parameetri tekstikasti parameeter, mis ilmub, nagu näidatud järgmisel pildil, sisesta parameeter 2
- Vajuta nuppu Execute ja allpool näidatud vormindatud vastus ilmub, nagu alloleval joonisel näidatud
Noh, see ongi tänase juhendi jaoks Swaggeri kasutamisest API dokumentatsiooni genereerimiseks ASP.NET Core WebAPI-s. Loodan, et on kasulik õppida Swaggerit API dokumentatsiooni genereerimiseks ASP.NET Core'is! KokkuvõteSee artikkel algab API dokumentatsiooni käsitsi kirjutamise valupunktist ja viib seejärel Swaggerini, tööriistani, mis genereerib automaatselt API dokumentatsiooni! Seejärel demonstreerime lihtsasti mõistetava teksti ja piltide kaudu, kuidas kasutada SwaggerUI-d, et genereerida API dokumentatsiooni ASP.NET Core WebAPI-s. Lõpuks tutvustan mõningaid Swaggeri keerukaid kasutusviise ASP.NET Core'is! Loodan, et see aitab sul Swaggerit ASP.NET Core'is kasutada!
| 
Postitatud 12.04.2019 14:14:46
|
|
|
|
