Často budete chcieť vytvoriť dokumentáciu pre svoje API. Na vytvorenie tejto dokumentácie môžete využiť výhodu Swagger - nástroja, ktorý je možné ľahko použiť na znázornenie vášho rozhrania API v používateľskom rozhraní. Keď vygenerujete dokumentáciu Swagger pre svoje API, môžete si pozrieť podpis svojich metód API a dokonca aj otestovať svoje metódy API.
Swashbuckle je open source projekt na generovanie dokumentov Swagger. Tento článok predstavuje diskusiu o tom, ako môžeme využiť funkciu Swashbuckle na generovanie interaktívnej dokumentácie pre naše RESTful API.
Vytvorte projekt ASP.Net Core
Najprv si vytvoríme projekt ASP.Net Core v Visual Studio. Za predpokladu, že je vo vašom systéme nainštalované Visual Studio 2017 alebo Visual Studio 2019, vytvorte nový projekt ASP.Net Core v Visual Studio podľa pokynov uvedených nižšie.
- Spustite Visual Studio IDE.
- Kliknite na „Vytvoriť nový projekt“.
- V okne „Vytvoriť nový projekt“ zo zoznamu zobrazených šablón vyberte možnosť „Webová aplikácia ASP.Net Core“.
- Kliknite na Ďalej.
- V nasledujúcom zobrazenom okne „Konfigurácia nového projektu“ zadajte názov a umiestnenie nového projektu.
- Kliknite na tlačidlo Vytvoriť.
- V okne „Vytvorenie novej webovej aplikácie ASP.Net Core“ vyberte z rozbaľovacieho zoznamu v hornej časti .Net Core ako runtime modul a ASP.Net Core 2.2 (alebo novší).
- Vyberte „API“ ako šablónu projektu a vytvorte nový projekt webového rozhrania ASP.Net Core Web API.
- Skontrolujte, či nie sú začiarknuté políčka „Povoliť podporu Docker“ a „Konfigurovať pre HTTPS“, pretože tu nebudeme tieto funkcie používať.
- Skontrolujte, či je overenie nastavené na „Bez overenia“, pretože tiež nebudeme používať overenie.
- Kliknite na tlačidlo Vytvoriť.
Nasledovaním týchto krokov vytvoríte nový projekt ASP.Net Core v Visual Studio. Tento projekt použijeme v ďalších častiach tohto článku na preskúmanie toho, ako môžeme vygenerovať dokumentáciu Swagger pre ValuesController.
Nainštalujte si middleware Swagger do ASP.Net Core
Ak ste úspešne vytvorili projekt ASP.Net Core, ďalšia vec, ktorú by ste mali urobiť, je pridať do svojho projektu potrebné balíčky NuGet. Ak to chcete urobiť, vyberte projekt v okne Solution Explorer, kliknite pravým tlačidlom myši a vyberte možnosť „Spravovať balíčky NuGet ....“ V okne Správcu balíkov NuGet vyhľadajte balíček Swashbuckle.AspNetCore a nainštalujte ho. Prípadne môžete balík nainštalovať pomocou konzoly NuGet Package Manager Console, ako je uvedené nižšie.
PM> Swashbuckle.AspNetCore pre inštaláciu balíka
Balík Swashbuckle.AspNetCore obsahuje potrebné nástroje na generovanie dokumentov API pre ASP.Net Core.
Nakonfigurujte middleware Swagger v ASP.Net Core
Ak chcete nakonfigurovať Swagger, napíšte nasledujúci kód do metódy ConfigureServices. Všimnite si, ako sa metóda rozšírenia AddSwaggerGen používa na zadanie metadát pre dokument API.
services.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", nové informácie
{
Verzia = "v1",
Title = "Ukáž ukážku",
Description = "Swagger Demo for ValuesController",
TermsOfService = "None",
Kontakt = nový Kontakt () {Name = "Joydip Kanjilal",
Email = "[email protected]",
Url = "www.google.com"}
});
});
Tiež by ste mali povoliť používateľské rozhranie Swagger v metóde Configure, ako je uvedené nižšie.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Tu je kompletný kód triedy Startup pre vašu potrebu.
pomocou Microsoft.AspNetCore.Builder;pomocou Microsoft.AspNetCore.Hosting;
pomocou Microsoft.AspNetCore.Mvc;
pomocou Microsoft.Extensions.Configuration;
pomocou Microsoft.Extensions.DependencyInjection;
pomocou Swashbuckle.AspNetCore.Swagger;
menný priestor SwaggerDemo
{
verejná trieda Startup
{
verejné spustenie (konfigurácia IConfigurácie)
{
Konfigurácia = konfigurácia;
}
public IConfiguration Configuration {get; }
public void ConfigureServices (služby IServiceCollection)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", nové informácie
{
Verzia = "v1",
Title = "Ukáž ukážku",
Description = "Swagger Demo for ValuesController",
TermsOfService = "None",
Kontakt = nový Kontakt () {Name = "Joydip Kanjilal",
Email = "[email protected]",
Url = "www.google.com"
}
});
});
}
public void Configure (aplikácia IApplicationBuilder,
IHostingEnvironment env)
{
if (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
To je všetko, čo musíte urobiť, aby ste mohli začať s programom Swagger.
Prejdite si používateľské rozhranie Swagger svojej aplikácie ASP.Net Core
Teraz sme pripravení spustiť aplikáciu a prehliadať koncový bod Swagger. Swagger UI sa zobrazí ako na obrázku 1 nižšie. Všimnite si, ako Swagger používa rôzne farby pre HTTP slovesá GET, PUT, POST a DELETE. Každý z koncových bodov zobrazených na obrázku 1 môžete vykonať priamo z používateľského rozhrania Swagger.
Vytvárajte komentáre XML v metódach akcie kontrolóra
Zatiaľ je všetko dobré. V dokumente Swagger vygenerovanom skôr neboli žiadne komentáre XML. Ak chcete v dokumente Swagger zobraziť komentáre XML, jednoducho ich napíšete do metód akcie ovládača.
Poďme si teraz napísať komentáre pre každú z metód akcie do ValuesController. Tu je aktualizovaná verzia nástroja ValuesController s komentármi XML pre každú z metód akcie.
[Route („api / [controller]“)][ApiController]
verejná trieda ValuesController: ControllerBase
{
///
/// Získajte metódu akcie bez akýchkoľvek argumentov
///
///
[HttpGet]
verejný ActionResult
Získať () {
vrátiť nový reťazec [] {"hodnota1", "hodnota2"};
}
///
/ / / Získať metódu akcie, ktorá prijme celé číslo ako argument
///
///
///
[HttpGet ("{id}")]
public ActionResult Get (int id)
{
návratová "hodnota";
}
///
/ / / Metóda post akcie na pridanie údajov
///
///
[HttpPost]
public void Post (hodnota reťazca [FromBody])
{
}
///
/ / / Vložte metódu akcie na úpravu údajov
///
///
///
[HttpPut ("{id}")]
public void Put (int id, hodnota reťazca [FromBody])
{
}
///
/ / / Odstrániť metódu akcie
///
///
[HttpDelete ("{id}")]
public void Delete (int id)
{
}
}
Zapnite komentáre XML v aplikácii Swagger
Upozorňujeme, že Swagger predvolene nezobrazuje komentáre XML. Túto funkciu musíte zapnúť. Kliknite pravým tlačidlom myši na Projekt, vyberte Vlastnosti a potom prejdite na kartu Vytvoriť. Na karte Vytvoriť začiarknite možnosť „Súbor dokumentácie XML“ a určte umiestnenie, kde sa vytvorí súbor dokumentácie XML.
Mali by ste tiež určiť, že komentáre XML by mali byť zahrnuté pri generovaní dokumentu Swagger napísaním nasledujúceho kódu v metóde ConfigureServices.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
A to je všetko, čo musíte urobiť, aby ste v aplikácii Swagger zapli komentáre XML.
Nastavte úvodnú adresu URL aplikácie na Swagger UI
Môžete zmeniť adresu URL na spustenie aplikácie a určiť, že sa používateľské rozhranie Swagger načíta pri spustení aplikácie. Kliknite pravým tlačidlom myši na Projekt a vyberte Vlastnosti. Potom prejdite na kartu Debug. Nakoniec zadajte hodnotu Launch Browser ako naparovanie, ako je to znázornené na obrázku 2.
Keď aplikáciu znova spustíte a prejdete na adresu URL Swagger, malo by sa zobraziť používateľské rozhranie Swagger, ako je to znázornené na obrázku 3 nižšie. Tentokrát si všimnite komentáre XML v každej z metód API.
Swashbuckle je skvelý nástroj na generovanie dokumentov Swagger pre vaše API. Najdôležitejšie je, že Swashbuckle sa ľahko konfiguruje a používa. So Swaggerom môžete urobiť oveľa viac, ako sme tu videli. Môžete prispôsobiť používateľské rozhranie Swagger pomocou kaskádových štýlov, zobrazovať hodnoty enum ako hodnoty reťazcov a vytvárať rôzne dokumenty Swagger pre rôzne verzie vášho API, aby sme vymenovali aspoň niektoré.
