Tento příspěvek byl naposledy upraven QWERTYU dne 12. 4. 2019 v 14:24
ÚvodPo použití asp.net Core pro vývoj API musí být psaní API dokumentace pro programátory bolestivý úkol, ale dokumentace musí být napsána, a pokud nejsou specifické požadavky na formát dokumentace, výsledná dokumentace závisí zcela na náladě vývojáře. Nebo být podrobnější, či jednodušší. Existuje tedy rychlý a efektivní způsob, jak vytvořit dokumentaci API? Odpověď je ano, Swagger je jeden z nejpopulárnějších nástrojů pro generování dokumentace REST API!
Proč používat Swagger jako nástroj pro generování dokumentace REST API- Swagger dokáže vytvořit interaktivní API konzoli, kterou vývojáři mohou využít k rychlému učení a experimentování s API.
- Swagger dokáže generovat SDK kód klienta pro implementace na různých platformách.
- Swagger soubory lze automaticky generovat z komentářů v kódu na mnoha různých platformách.
- Swagger má silnou komunitu s mnoha silnými přispěvateli.
Jak použít Swagger k generování API dokumentace v asp.net jádru?- Swashbuckle.AspNetCore je open-source projekt, který generuje dokumentaci Swagger pro ASP.NET Core Web API.
- NSwag je další open-source projekt pro integraci Swagger UI nebo ReDoc do ASP.NET Core Web API. Poskytuje způsob, jak generovat klientský kód pro API v C# a TypeScriptu.
Následuje příklad Swashbuckle.AspNetCoreJaké jsou složky Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Zobrazuje objekt SwaggerDocument jako model objektu Swagger a middleware pro JSON endpointy.
- Swashbuckle.AspNetCore.SwaggerGen: Generátor Swagger, který generuje objekty SwaggerDocument přímo z tras, kontrolérů a modelů. Často je kombinován s Swagger endpoint middleware, aby automaticky zpřístupnil Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Vestavěná verze nástroje Swagger UI. Interpretuje Swagger JSON tak, aby vytvářel přizpůsobitelné a bohaté zážitky, které popisují funkčnost webových API. Obsahuje vestavěné testovací nástroje pro běžné metody.
Jak nainstalovat Swashbuckle s vs2017?
První způsob: instalace z okna Console Správce balíčků
- Přejděte na Pohledy > jiné Windows > Package Manager Console
- Přejděte do adresáře, který obsahuje soubor TodoApi.csproj
- Prosím, proveďte následující příkaz · Install-Package Swashbuckle.AspNetCore
-
Druhý způsob: Z dialogu Spravovat NuGet balíčky:- Klikněte pravým tlačítkem na projekt v Průzkumníku řešení > Spravovat NuGet balíčky
- Nastavte zdroj balíčku na nuget.org
- Do vyhledávacího pole zadejte "Swashbuckle.AspNetCore"
- Vyberte balíček Swashbuckle.AspNetCore na záložce Procházet a klikněte na Instalovat
-
Přidat a nastavit middleware SwaggerNejprve představte jmenný prostor: Přidejte generátor Swagger do kolekce služeb metodou Startup.ConfigureServices: uStartup.Configuremetoda, povolit middleware pro servírování generovaného JSON dokumentu a Swagger UI:
Spusť aplikaci a přejít na nihttps://localhost:<port>/swagger/v1/swagger.json。 Výsledná dokumentace popisující koncový bod je zobrazena ve formátu JSON následovně.
Dostupnéhttps://localhost:<port>/SwaggerNajděte uživatelské rozhraní Swagger. Prohlédněte si dokumentaci API přes uživatelské rozhraní Swagger, jak je uvedeno níže.
Pro aplikaci kořene (http://localhost<port>:/) pro poskytnutí uživatelského rozhraní Swagger prosím zadejteRoutePrefixVlastnost je nastavena na prázdný řetězec:
Pokročilé využití Swaggeru (úpravy a rozšíření)Použijte Swagger k přidání vysvětlujících informací do API dokumentaceNásledující konfigurační operace jsou prováděny metodou AddSwaggerGen, která přidává informace jako autor, licence a popis: Informace o verzi zobrazení uživatelského rozhraní waggeru jsou zobrazeny na následujícím obrázku: Přidávat komentáře k metodám rozhraníNejprve klikněme na API, rozbalme podle obrázku níže, mohou tam být žádné komentáře, jak přidat komentáře? Přidejte komentáře k dokumentu s třemi/jak je vidět na obrázku níže, jak je uvedeno níže Pak spusťte projekt a vraťte se do swaggerUI, jestli se komentář objeví Stále se neobjevil, neboj, podívej se dolů! Povolit XML anotaceXML anotace můžete povolit následujícími metodami: - Klikněte pravým tlačítkem na projekt v Průzkumníku řešení a vyberte Vlastnosti
- Podívejte se na pole XML Document File v sekci Output na záložce Build
-
Povolení XML anotací poskytuje ladicí informace pro nedokumentované běžné typy a členy. Pokud se například objeví mnoho varovných zpráv, následující zpráva označuje porušení varovného kódu 1591:
Co když máte OCD a chcete varování zrušit? Můžete zrušit, jak je vidět na obrázku níže
Všimněte si cesty k výše generovanému xml souboru dokumentu,
Poznámka: 1. Pro operační systémy Linux nebo ne-Windows jsou názvy souborů a cesty citlivé na velká písmena. Například soubor "SwaggerDemo.xml" funguje na Windows, ale ne na CentOS. 2. Pro získání cesty aplikace se doporučuje použít AppContext.BaseDirectory k jejímu získání Znovu sestavte a spusťte projekt, abyste zjistili, jestli se komentáře objeví Z výše uvedené operace lze shrnout, že uživatelské rozhraní Swagger zobrazuje <summary> interní text prvků výše uvedeného komentářového kódu jako velké API komentáře! Samozřejmě můžete také přidat prvek poznámek do dokumentace Get How To. Může doplnit <summary> informace specifikované v prvku a poskytnout spolehlivější uživatelské rozhraní Swagger. <remarks> Obsah prvků může obsahovat text, JSON nebo XML. Kód je následující: Otestujte API rozhraní pomocí SwaggerUIPojďme si rozhraní pomocí SwaggerUI na malém příkladu projít
- Klikněte na API rozhraní, které je potřeba otestovat, a pak klikněte na tlačítko "Vyzkoušet to" vlevo a vpravo v sekci Parametry
- Zadejte parametr do textového pole parametru, které se zobrazí, jak je znázorněno na následujícím obrázku, zadejte parametr 2
- Klikněte na tlačítko Execute a zobrazí se níže naformátovaná odpověď, jak je znázorněno na obrázku níže
To je vše k dnešnímu tutoriálu o používání Swaggeru k generování API dokumentace v ASP.NET Core WebApi. Doufám, že vám pomůže naučit se používat Swagger k generování API dokumentace v ASP.NET Core! shrnutíTento článek začíná problémem ručního psaní API dokumentace a poté vede k Swaggeru, nástroji, který automaticky generuje API dokumentaci! Poté prostřednictvím snadno pochopitelného textu a obrázků ukážeme, jak použít SwaggerUI k generování API dokumentace v ASP.NET Core WebApi. Nakonec představím několik pokročilých využití Swaggeru v ASP.NET Core! Doufám, že ti to pomůže používat Swagger v ASP.NET Core!
| 
Zveřejněno 12.04.2019 14:14:46
|
|
|
|
