Ta objava je bila nazadnje urejena s strani QWERTYU 12. 4. 2019 ob 14:24
UvodPo uporabi asp.net Core za razvoj API-jev mora biti pisanje dokumentacije API-jev boleča naloga za programerje, vendar mora biti dokumentacija napisana, in če ni posebnih zahtev glede formata dokumentacije, je končna dokumentacija povsem odvisna od razpoloženja razvijalca. Ali pa bolj podrobno ali preprostejše. Ali obstaja hiter in učinkovit način za izdelavo dokumentacije API-ja? Odgovor je da, Swagger je eno najbolj priljubljenih orodij za generiranje dokumentacije REST API-jev!
Zakaj uporabljati Swagger kot orodje za generiranje dokumentacije REST API-jev- Swagger lahko ustvari interaktivno API konzolo, ki jo razvijalci uporabljajo za hitro učenje in eksperimentiranje z API-ji.
- Swagger lahko generira SDK kodo odjemalcev za implementacije na različnih platformah.
- Swagger datoteke je mogoče samodejno generirati iz komentarjev kode na različnih platformah.
- Swagger ima močno skupnost z mnogimi močnimi sodelavci.
Kako uporabiti Swagger za generiranje API dokumentacije v asp.net jedru?- Swashbuckle.AspNetCore je odprtokodni projekt, ki generira Swagger dokumentacijo za ASP.NET Core Web API.
- NSwag je še en odprtokodni projekt za integracijo uporabniškega vmesnika Swagger ali ReDoc v ASP.NET jedrne spletne API-je. Omogoča generiranje kode odjemalcev v C# in TypeScript za API-je.
Spodaj je primer Swashbuckle.AspNetCoreKateri so sestavni deli Swashbuckla?- Swashbuckle.AspNetCore.Swagger: Prikazuje objekt SwaggerDocument kot Swagger objektni model in vmesno programsko opremo za JSON končne točke.
- Swashbuckle.AspNetCore.SwaggerGen: Generator Swagger, ki generira objekte SwaggerDocument neposredno iz poti, krmilnikov in modelov. Pogosto se združuje s Swagger endpoint middleware programsko opremo, da samodejno razkrije Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Vgrajena različica orodja Swagger UI. Interpretira Swagger JSON kot gradnjo prilagodljivih, bogatih izkušenj, ki opisujejo funkcionalnost spletnih API-jev. Vključuje vgrajena orodja za testiranje pogostih metod.
Kako namestiti Swashbuckle z vs2017?
Prvi način: namestitev iz konzolnega okna Package Manager
- Pojdite na Poglede > drugih Windows > Package Manager konzoli
- Pojdite do mape, ki vsebuje datoteko TodoApi.csproj
- Prosimo, izvedite naslednji ukaz · Install-Package Swashbuckle.AspNetCore
-
Drugi način: Iz pogovornega okna Upravljanje paketov NuGet:- Desni klik na projekt v Solution Explorer > upravljanje NuGet paketov
- Nastavi izvorno kodo paketa na nuget.org
- V iskalno polje vpišite "Swashbuckle.AspNetCore"
- Izberite paket Swashbuckle.AspNetCore iz zavihka Brskanje in kliknite Namesti
-
Dodaj in nastavi Swagger vmesno programsko opremoNajprej predstavite imenski prostor: Dodajte generator Swagger v zbirko storitev v metodi Startup.ConfigureServices: naStartup.Configuremetoda, omogočiti vmesno programsko opremo za strežbo generiranemu JSON dokumentu in uporabniškemu vmesniku Swagger:
Zaženi aplikacijo in pojdi do njehttps://localhost:<port>/swagger/v1/swagger.json。 Nastala dokumentacija, ki opisuje končno točko, je prikazana v JSON formatu na naslednji način.
Na voljohttps://localhost:<port>/samozavestPoišči uporabniški vmesnik Swagger. Prebrskajte dokumentacijo API-ja preko uporabniškega vmesnika Swagger, kot je prikazano spodaj.
Za uporabo korena (http://localhost<port>:/) za zagotavljanje uporabniškega vmesnika Swagger prosim vstavitePredpona potiLastnost je nastavljena na prazen niz:
Napredna uporaba Swaggerja (prilagajanje in razširitve)Uporabite Swagger za dodajanje pojasnjevalnih informacij v dokumentacijo API-jaNaslednje konfiguracijske operacije se izvajajo v metodi AddSwaggerGen, ki dodaja informacije, kot so avtor, licenca in opis: Informacije o različici za prikaz uporabniškega vmesnika wagger so prikazane na naslednji sliki: Dodaj komentarje k vmesnim metodamNajprej kliknimo na API, razširimo, kot je prikazano na spodnji sliki, ali ni komentarjev, kako dodati komentarje? Dodajte komentarje k dokumentu s tremi/kot je prikazano na spodnji sliki, kot je prikazano spodaj Nato zaženi projekt in se vrni v swaggerUI, da vidiš, ali se komentar pojavi Še vedno se ni pojavila, ne skrbi, poglej dol! Omogočite XML oznakeXML oznake lahko omogočite na naslednje načine: - Desni klik na projekt v Solution Explorer in izberite Lastnosti
- Poglej polje XML Document File pod razdelkom Output na zavihku Build
-
Omogočanje XML oznak zagotavlja informacije za odpravljanje napak za nedokumentirane pogoste tipe in člane. Če se na primer pojavi veliko opozorilnih sporočil, naslednje sporočilo označuje kršitev opozorilnega kodeksa 1591:
Kaj pa, če imaš OCD in želiš preklicati opozorilo? Lahko prekličete, kot je prikazano na spodnji sliki
Opazujte pot do zgoraj generirane datoteke xml dokumenta,
Opomba: 1. Za Linux ali ne-Windows operacijske sisteme so imena datotek in poti občutljivi na velike in male črke. Na primer, datoteka "SwaggerDemo.xml" deluje na Windows, ne pa na CentOS. 2. Za pridobitev poti aplikacije je priporočljivo uporabiti AppContext.BaseDirectory Ponovno zgradi in zaženi projekt, da vidiš, ali se pojavijo komentarji Iz zgornje operacije lahko povzamemo, da uporabniški vmesnik Swagger prikazuje <summary> notranje besedilo elementov zgornje kode komentarja kot velike komentarje API-ja! Seveda lahko dodate tudi element opomb v dokumentacijo Get How To. Lahko dopolni <summary> informacije, navedene v elementu, in zagotovi bolj zanesljiv uporabniški vmesnik Swaggerja. <remarks> Elementna vsebina lahko vsebuje besedilo, JSON ali XML. Koda je naslednja: Preizkusite API vmesnik s SwaggerUIPoglejmo razhroščevanje vmesnika preko SwaggerUI na majhnem primeru
- Kliknite na API vmesnik, ki ga je treba testirati, nato pa kliknite gumb "Preizkusi to" levo in desno od Parametrov
- Vnesite parameter v besedilno polje parametra, ki se pojavi, kot je prikazano na naslednji sliki, vnesite parameter 2
- Kliknite gumb Execute in prikazal se bo oblikovan odgovor, prikazan spodaj, kot je prikazano na spodnji sliki
No, to je to za današnji vodič o uporabi Swaggerja za generiranje API dokumentacije v ASP.NET Core WebApi. Upam, da vam bo v pomoč, če se naučite uporabljati Swagger za generiranje API dokumentacije v ASP.NET Core! PovzetekTa članek se začne s težavo pisanja dokumentacije API-jev ročno, nato pa vodi do Swaggerja, orodja, ki samodejno generira dokumentacijo API-ja! Nato bomo s pomočjo enostavnega besedila in slik pokazali, kako uporabiti SwaggerUI za generiranje API dokumentacije v ASP.NET jedrnem WebApi-ju. Nazadnje bom predstavil nekaj naprednih uporab Swaggerja v ASP.NET Core! Upam, da ti bo pomagalo uporabljati Swagger v ASP.NET Core!
| 
Objavljeno na 12. 04. 2019 14:14:46
|
|
|
|
