Šį pranešimą paskutinį kartą redagavo QWERTYU 2019-4-12 14:24
ĮvadasPanaudojus asp.net Core API kūrimui, API dokumentacijos rašymas programuotojams turi būti skausminga užduotis, tačiau dokumentacija turi būti parašyta, o jei nėra konkrečių reikalavimų dokumentacijos formatui, galutinė dokumentacija visiškai priklauso nuo kūrėjo nuotaikos. Arba būkite išsamesni ar paprastesni. Taigi ar yra greitas ir efektyvus būdas sukurti API dokumentaciją? Atsakymas yra taip, "Swagger" yra vienas populiariausių REST API dokumentacijos generavimo įrankių!
Kodėl verta naudoti "Swagger" kaip REST API dokumentacijos generavimo įrankį- "Swagger" gali sukurti interaktyvią API konsolę, kurią kūrėjai gali naudoti norėdami greitai išmokti ir eksperimentuoti su API.
- "Swagger" gali generuoti kliento SDK kodą, skirtą diegti įvairiose platformose.
- "Swagger" failai gali būti automatiškai generuojami iš kodo komentarų daugelyje skirtingų platformų.
- "Swagger" turi stiprią bendruomenę su daugybe stiprių bendradarbių.
Kaip naudoti "Swagger" API dokumentacijai generuoti asp.net branduolyje?- "Swashbuckle.AspNetCore" yra atvirojo kodo projektas, generuojantis "Swagger" dokumentaciją "ASP.NET Core Web API".
- NSwag yra dar vienas atvirojo kodo projektas, skirtas integruoti Swagger UI arba ReDoc į ASP.NET Core Web API. Tai suteikia būdą generuoti C# ir TypeScript kliento kodą API.
Toliau pateikiamas Swashbuckle.AspNetCore pavyzdysKokie yra "Swashbuckle" komponentai?- Swashbuckle.AspNetCore.Swagger: atskleidžia "SwaggerDocument" objektą kaip "Swagger" objekto modelį ir tarpinę programinę įrangą, skirtą JSON galiniams punktams.
- Swashbuckle.AspNetCore.SwaggerGen: Swagger generatorius, generuojantis SwaggerDocument objektus tiesiai iš maršrutų, valdiklių ir modelių. Jis dažnai derinamas su "Swagger" galinio taško tarpine programine įranga, kad automatiškai atskleistų "Swagger JSON".
- Swashbuckle.AspNetCore.SwaggerUI: įterptoji "Swagger" vartotojo sąsajos įrankio versija. Jis interpretuoja "Swagger JSON", kad sukurtų pritaikomą, turtingą patirtį, apibūdinančią žiniatinklio API funkcionalumą. Jame yra integruoti įprastų metodų testavimo įrankiai.
Kaip įdiegti "Swashbuckle" su vs2017?
Pirmasis būdas: įdiekite iš "Package Manager Console" lango
- Eikite į rodinius > kitą "Windows >" paketų tvarkyklės konsolę
- Eikite į katalogą, kuriame yra failas TodoApi.csproj
- Vykdykite šią komandą · Įdiegti paketą Swashbuckle.AspNetCore
-
Antrasis būdas: Iš dialogo lango Tvarkyti NuGet paketus:- Dešiniuoju pelės mygtuku spustelėkite projektą sprendimų naršyklėje> tvarkytumėte "NuGet" paketus
- Nustatyti paketo šaltinį į nuget.org
- Paieškos laukelyje įveskite "Swashbuckle.AspNetCore"
- Pasirinkite Swashbuckle.AspNetCore paketą skirtuke Naršyti ir spustelėkite Įdiegti
-
Pridėkite ir konfigūruokite "Swagger" tarpinę programinę įrangąPirmiausia pristatykite vardų sritį: Įtraukite "Swagger" generatorių į paslaugų rinkinį naudodami "Startup.ConfigureServices" metodą: priePaleisti.Konfigūruotimetodas, įgalinkite tarpinę programinę įrangą aptarnauti sugeneruotą JSON dokumentą ir "Swagger" vartotojo sąsają:
Paleiskite programą ir eikite į jąhttps://localhost:<port>/swagger/v1/swagger.json。 Gauta dokumentacija, apibūdinanti galinį tašką, rodoma JSON formatu, kaip nurodyta toliau.
Yrahttps://localhost:<port>/swaggerRaskite "Swagger" vartotojo sąsają. Naršykite API dokumentaciją naudodami "Swagger" vartotojo sąsają, kaip parodyta toliau.
Norėdami pritaikyti šaknį (http://localhost:<port>/) pateikti Swagger vartotojo sąsają, prašome įdėtiRoutePrefixYpatybė nustatyta kaip tuščia eilutė:
Išplėstinis "Swagger" naudojimas (pritaikymas ir plėtiniai)Naudokite "Swagger", kad pridėtumėte aiškinamąją informaciją prie API dokumentacijosŠios konfigūravimo operacijos atliekamos naudojant AddSwaggerGen metodą, kuris prideda informaciją, pvz., autoriaus, licencijos ir aprašo informaciją: "Wagger" vartotojo sąsajos rodymo versijos informacija parodyta šiame paveikslėlyje: Komentarų įtraukimas į sąsajos metodusPirmiausia spustelėkime API, išplėskime, kaip parodyta paveikslėlyje žemiau, ar gali būti komentarų, kaip pridėti komentarų? Pridėkite dokumento komentarus su trimis / kaip parodyta paveikslėlyje žemiau, kaip parodyta toliau Tada paleiskite projektą ir grįžkite į swaggerUI, kad pamatytumėte, ar komentaras pasirodo Vis dar nepasirodė, nesijaudinkite, pažvelkite žemyn! Įgalinti XML komentarusXML komentarus galite įjungti šiais būdais: - Dešiniuoju pelės mygtuku spustelėkite projektą sprendimų naršyklėje ir pasirinkite Ypatybės
- Peržiūrėkite XML dokumento failo laukelį, esantį skirtuko Kurti skyriuje Išvestis
-
Įgalinus XML komentarus, pateikiama nedokumentuotų bendrųjų tipų ir narių derinimo informacija. Pavyzdžiui, jei rodoma daug įspėjamųjų pranešimų, šis pranešimas rodo įspėjimo kodo 1591 pažeidimą:
Ką daryti, jei sergate OKS ir norite atšaukti įspėjimą? Galite atšaukti, kaip parodyta paveikslėlyje žemiau
Atkreipkite dėmesį į aukščiau sugeneruoto xml dokumento failo kelią,
Nata: 1. "Linux" arba ne "Windows" operacinėse sistemose failų pavadinimai ir keliai skiria didžiąsias ir mažąsias raides. Pavyzdžiui, failas "SwaggerDemo.xml" veikia "Windows", bet ne "CentOS". 2. Norint gauti programos kelią, rekomenduojama jį gauti naudojant AppContext.BaseDirectory Iš naujo sukurkite ir paleiskite projektą, kad pamatytumėte, ar rodomi komentarai Iš aukščiau pateiktos operacijos galima apibendrinti, kad "Swagger" vartotojo sąsaja rodo <summary> vidinį aukščiau pateikto komentaro kodo elementų tekstą kaip API didelius komentarus! Žinoma, pastabų elementą taip pat galite įtraukti į dokumentaciją Gauti instrukcijas. Jis gali papildyti <summary> elemente nurodytą informaciją ir suteikti patikimesnę "Swagger" vartotojo sąsają. <remarks> Elemento turinyje gali būti teksto, JSON arba XML. Kodas yra toks: Išbandykite API sąsają naudodami "SwaggerUI"Derinkime sąsają naudodami "SwaggerUI" naudodami nedidelį pavyzdį
- Spustelėkite API sąsają, kurią reikia išbandyti, tada spustelėkite mygtuką "Išbandyti" parametrų kairėje ir dešinėje
- Įveskite parametrą į pasirodžiusį parametro teksto laukelį, kaip parodyta šiame paveikslėlyje, įveskite 2 parametrą
- Spustelėkite mygtuką Vykdyti ir pasirodys toliau parodytas suformatuotas atsakymas, kaip parodyta paveikslėlyje žemiau
Na, tai viskas šiandienos pamokai apie "Swagger" naudojimą API dokumentacijai generuoti "ASP.NET Core WebApi". Tikiuosi, kad jums bus naudinga išmokti naudoti "Swagger" API dokumentacijai generuoti ASP.NET Core! suvestinėŠis straipsnis prasideda nuo API dokumentacijos rašymo ranka skausmo, o tada veda prie "Swagger" – įrankio, kuris automatiškai generuoja API dokumentaciją! Tada, naudodami lengvai suprantamą tekstą ir paveikslėlius, parodysime, kaip naudoti "SwaggerUI" API dokumentacijai generuoti "ASP.NET Core WebApi". Galiausiai pristatysiu keletą išplėstinių "Swagger" naudojimo būdų "ASP.NET Core"! Tikiuosi, kad tai padės jums naudoti "Swagger" ASP.NET Core!
| 
Paskelbta 2019-04-12 14:14:46
|
|
|
|
