Tento príspevok naposledy upravil QWERTYU 12. 4. 2019 o 14:24
ZavedeniePo použití asp.net Core na vývoj API musí byť písanie dokumentácie API pre programátorov bolestivou úlohou, ale dokumentácia musí byť napísaná, a ak nie sú špecifické požiadavky na formát dokumentácie, finálna dokumentácia závisí výlučne od nálady vývojára. Alebo byť podrobnejší, či jednoduchší. Existuje teda rýchly a efektívny spôsob, ako vytvoriť dokumentáciu API? Odpoveď je áno, Swagger je jeden z najpopulárnejších nástrojov na generovanie dokumentácie REST API!
Prečo používať Swagger ako nástroj na generovanie dokumentácie REST API- Swagger dokáže vytvoriť interaktívnu API konzolu, ktorú môžu vývojári využiť na rýchle učenie sa a experimentovanie s API.
- Swagger dokáže generovať SDK kód klienta pre implementácie na rôznych platformách.
- Swagger súbory môžu byť automaticky generované z komentárov v kóde na mnohých rôznych platformách.
- Swagger má silnú komunitu s mnohými silnými prispievateľmi.
Ako používať Swagger na generovanie API dokumentácie v asp.net jadre?- Swashbuckle.AspNetCore je open-source projekt, ktorý generuje dokumentáciu Swagger pre ASP.NET Core Web API.
- NSwag je ďalší open-source projekt na integráciu Swagger UI alebo ReDoc do ASP.NET Core Web API. Poskytuje spôsob, ako generovať klientský kód pre API v C# a TypeScript.
Nasleduje príklad Swashbuckle.AspNetCoreAké sú komponenty Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Sprístupňuje objekt SwaggerDocument ako Swagger objektový model a middleware pre JSON endpointy.
- Swashbuckle.AspNetCore.SwaggerGen: Generátor Swagger, ktorý generuje objekty SwaggerDocument priamo z rút, kontrolérov a modelov. Často sa kombinuje so Swagger endpoint middleware, aby automaticky sprístupnil Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Zabudovaná verzia nástroja Swagger UI. Interpretuje Swagger JSON tak, že vytvára prispôsobiteľné, bohaté zážitky, ktoré popisujú funkcionalitu webových API. Obsahuje zabudované testovacie nástroje pre bežné metódy.
Ako nainštalovať Swashbuckle s vs2017?
Prvý spôsob: inštalovať z okna Package Manager Console
- Prejdite na zobrazenia > iných Windows > Package Manager Console
- Prejdite do adresára, ktorý obsahuje súbor TodoApi.csproj
- Prosím, vykonajte nasledujúci príkaz · Install-Package Swashbuckle.AspNetCore
-
Druhý spôsob: Z dialógu Spravovať balíky NuGet:- Kliknite pravým tlačidlom myši na projekt v Prieskumníku riešení > Spravovať balíky NuGet
- Nastavte zdrojový kód balíka na nuget.org
- Napíšte do vyhľadávacieho poľa "Swashbuckle.AspNetCore"
- Vyberte balík Swashbuckle.AspNetCore z karty Prehliadanie a kliknite na Inštalovať
-
Pridať a nakonfigurovať middleware SwaggerNajprv predstavte menný priestor: Pridajte generátor Swagger do kolekcie služieb v metóde Startup.ConfigureServices: priStartup.Configuremetóda, povoliť middleware na obsluhu generovaného JSON dokumentu a Swagger UI:
Spustite aplikáciu a prejdite na ňuhttps://localhost:<port>/swagger/v1/swagger.json。 Výsledná dokumentácia popisujúca koncový bod je zobrazená vo formáte JSON nasledovne.
Dostupnéhttps://localhost:<port>/sebavedomieNájdite používateľské rozhranie Swagger. Prezrite si dokumentáciu API cez Swagger UI, ako je uvedené nižšie.
Na aplikáciu koreňa (http://localhost:<port>/) aby ste poskytli používateľské rozhranie Swagger, prosím, vložteRoutePrefixVlastnosť je nastavená na prázdny reťazec:
Pokročilé využitie Swaggeru (prispôsobenie a rozšírenia)Použite Swagger na pridanie vysvetľujúcich informácií do dokumentácie APINasledujúce konfiguračné operácie sa vykonávajú v metóde AddSwaggerGen, ktorá pridáva informácie ako autor, licencia a popis: Informácie o verzii zobrazenia používateľského rozhrania waggera sú zobrazené na nasledujúcom obrázku: Pridávať komentáre k metódam rozhraniaNajprv kliknime na API, rozbalme podľa obrázka nižšie, môžu tam byť žiadne komentáre, ako pridať komentáre? Pridajte komentáre k dokumentu s tromi/ako je zobrazené na obrázku nižšie, ako je uvedené nižšie Potom spustite projekt a vráťte sa do swaggerUI, či sa komentár zobrazí Stále sa neukázal, neboj sa, pozri dole! Povoliť XML anotácieXML anotácie môžete povoliť pomocou nasledujúcich metód: - Kliknite pravým tlačidlom myši na projekt v Prieskumníku riešení a vyberte Vlastnosti
- Pozrite sa na pole XML Document File v sekcii Output na karte Build
-
Povolenie XML anotácií poskytuje ladiace informácie pre nedokumentované spoločné typy a členov. Ak sa napríklad objaví veľa varovných správ, nasledujúca správa naznačuje porušenie varovného kódu 1591:
Čo ak máte OCD a chcete varovanie zrušiť? Môžete zrušiť, ako je znázornené na obrázku nižšie
Všimnite si cestu k xml súboru vygenerovanému vyššie,
Nota: 1. Pre operačné systémy Linux alebo ne-Windows sú názvy súborov a cesty citlivé na veľkosť písmen. Napríklad súbor "SwaggerDemo.xml" funguje na Windows, ale nie na CentOS. 2. Na získanie cesty aplikácie sa odporúča použiť AppContext.BaseDirectory na jej získanie Obnovte projekt a spustite ho, aby ste zistili, či sa objavia komentáre Z vyššie uvedenej operácie možno zhrnúť, že Swagger UI zobrazuje <summary> interný text prvkov vyššie uvedeného komentára ako veľké API komentáre! Samozrejme, môžete tiež pridať prvok poznámok do dokumentácie Get how-to. Môže dopĺňať <summary> informácie špecifikované v prvku a poskytovať spoľahlivejšie používateľské rozhranie Swagger. <remarks> Obsah prvkov môže obsahovať text, JSON alebo XML. Kód je nasledovný: Otestujte API rozhranie pomocou SwaggerUIPoďme debugovať rozhranie cez SwaggerUI na malom príklade
- Kliknite na API rozhranie, ktoré treba otestovať, a potom kliknite na tlačidlo "Vyskúšať to" vľavo a vpravo v sekcii Parameters
- Zadajte parameter do textového poľa parametra, ktorý sa zobrazí, ako je znázornené na nasledujúcom obrázku, zadajte parameter 2
- Kliknite na tlačidlo Execute a zobrazí sa naformátovaná odpoveď zobrazená nižšie, ako je znázornené na obrázku nižšie
No, to je všetko z dnešného tutoriálu o používaní Swaggeru na generovanie API dokumentácie v ASP.NET Core WebApi. Dúfam, že vám pomôže naučiť sa používať Swagger na generovanie API dokumentácie v ASP.NET Core! súhrnTento článok začína problémom písania dokumentácie API ručne a potom vedie k nástroju Swagger, ktorý automaticky generuje dokumentáciu API! Potom prostredníctvom ľahko pochopiteľného textu a obrázkov ukážeme, ako použiť SwaggerUI na generovanie API dokumentácie v ASP.NET Core WebApi. Nakoniec predstavím niektoré pokročilé využitia Swaggeru v ASP.NET Core! Dúfam, že ti pomôže používať Swagger v ASP.NET Core!
| 
Zverejnené 12. 4. 2019 14:14:46
|
|
|
|
