Často budete chtít vytvořit dokumentaci pro své API. Chcete-li vytvořit tuto dokumentaci, můžete využít výhod Swagger - nástroje, který lze snadno použít k reprezentaci uživatelského rozhraní vašeho rozhraní API. Jakmile vygenerujete dokumentaci Swagger pro vaše API, můžete si prohlédnout podpis svých metod API a dokonce i otestovat své metody API.
Swashbuckle je open source projekt pro generování dokumentů Swagger. Tento článek představuje diskusi o tom, jak můžeme využít Swashbuckle ke generování interaktivní dokumentace pro naše RESTful API.
Vytvořte projekt ASP.Net Core
Nejprve si vytvořme projekt ASP.Net Core v sadě Visual Studio. Za předpokladu, že je ve vašem systému nainstalována sada Visual Studio 2017 nebo Visual Studio 2019, vytvořte nový projekt ASP.Net Core v sadě Visual Studio podle pokynů uvedených níže.
- Spusťte Visual Studio IDE.
- Klikněte na „Vytvořit nový projekt“.
- V okně „Vytvořit nový projekt“ vyberte ze zobrazeného seznamu šablon „Webová aplikace ASP.Net Core“.
- Klikněte na Další.
- V dalším okně „Konfigurace nového projektu“ zadejte název a umístění nového projektu.
- Klikněte na Vytvořit.
- V okně „Vytvořit novou webovou aplikaci ASP.Net Core“ vyberte jako běhové prostředí .Net Core a z rozevíracího seznamu v horní části ASP.Net Core 2.2 (nebo novější).
- Vyberte „API“ jako šablonu projektu a vytvořte nový projekt webového rozhraní API ASP.Net Core.
- Ujistěte se, že políčka „Povolit podporu Dockeru“ a „Konfigurovat pro HTTPS“ nejsou zaškrtnuta, protože zde tyto funkce nebudeme používat.
- Ujistěte se, že je ověřování nastaveno na „Žádné ověřování“, protože také nebudeme používat ověřování.
- Klikněte na Vytvořit.
Následující kroky vytvoří nový projekt ASP.Net Core v sadě Visual Studio. Tento projekt použijeme v následujících částech tohoto článku, abychom zjistili, jak můžeme vygenerovat dokumentaci Swagger pro ValuesController.
Nainstalujte Swagger middleware do ASP.Net Core
Pokud jste úspěšně vytvořili projekt ASP.Net Core, další věcí, kterou byste měli udělat, je přidat do vašeho projektu potřebné balíčky NuGet. Chcete-li to provést, vyberte projekt v okně Průzkumníka řešení, klikněte pravým tlačítkem a vyberte „Spravovat balíčky NuGet ....“ V okně Správce balíčků NuGet vyhledejte balíček Swashbuckle.AspNetCore a nainstalujte jej. Alternativně můžete balíček nainstalovat pomocí konzoly Správce balíčků NuGet, jak je znázorněno níže.
PM> Instalovat balíček Swashbuckle.AspNetCore
Balíček Swashbuckle.AspNetCore obsahuje potřebné nástroje pro generování dokumentů API pro ASP.Net Core.
Nakonfigurujte middleware Swagger v ASP.Net Core
Chcete-li nakonfigurovat Swagger, napište následující kód v metodě ConfigureServices. Všimněte si, jak se metoda rozšíření AddSwaggerGen používá k určení metadat pro dokument API.
services.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", nové informace
{
Verze = "v1",
Title = "Swagger Demo",
Description = "Swagger Demo for ValuesController",
TermsOfService = "None",
Contact = new Contact () {Name = "Joydip Kanjilal",
Email = "[email protected]",
Url = "www.google.com"}
});
});
Měli byste také povolit uživatelské rozhraní Swagger v metodě Configure, jak je znázorněno níže.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Zde je kompletní kód třídy Startup pro vaši referenci.
pomocí Microsoft.AspNetCore.Builder;pomocí Microsoft.AspNetCore.Hosting;
pomocí Microsoft.AspNetCore.Mvc;
pomocí Microsoft.Extensions.Configuration;
pomocí Microsoft.Extensions.DependencyInjection;
pomocí Swashbuckle.AspNetCore.Swagger;
jmenný prostor SwaggerDemo
{
veřejná třída Spuštění
{
veřejné spuštění (konfigurace IConfiguration)
{
Konfigurace = konfigurace;
}
public IConfiguration Configuration {get; }
public void ConfigureServices (služby IServiceCollection)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", nové informace
{
Verze = "v1",
Title = "Swagger Demo",
Description = "Swagger Demo for ValuesController",
TermsOfService = "None",
Contact = new Contact () {Name = "Joydip Kanjilal",
Email = "[email protected]",
Url = "www.google.com"
}
});
});
}
public void Configure (aplikace 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še, co musíte udělat, abyste mohli začít používat Swagger.
Procházejte uživatelské rozhraní Swagger vaší aplikace ASP.Net Core
Nyní jsme připraveni spustit aplikaci a procházet koncový bod Swagger. Uživatelské rozhraní Swagger se zobrazí jako na obrázku 1 níže. Všimněte si, jak Swagger používá různé barvy pro HTTP slovesa GET, PUT, POST a DELETE. Každý z koncových bodů zobrazených na obrázku 1 můžete spustit přímo z uživatelského rozhraní Swagger.
Vytvořte komentáře XML v akčních metodách vašeho řadiče
Zatím je vše dobré. V dříve generovaném dokumentu Swagger nebyly žádné komentáře XML. Chcete-li v dokumentu Swagger zobrazit komentáře XML, jednoduše tyto komentáře napíšete do metod akce vašeho řadiče.
Pojďme nyní napsat komentáře ke každé z metod akce v ValuesController. Zde je aktualizovaná verze ValuesController s komentáři XML pro každou z metod akce.
[Route ("api / [controller]")] [ApiController]
veřejná třída ValuesController: ControllerBase
{
///
/// Získejte metodu akce bez jakéhokoli argumentu
///
///
[HttpGet]
public ActionResult Dostat() {
vrátit nový řetězec [] {"value1", "value2"};
}
///
/// Získejte metodu akce, která přijímá celé číslo jako argument
///
///
///
[HttpGet ("{id}")]
public ActionResult Get (int id)
{
vrátit "hodnotu";
}
///
/// Metoda odeslání akce pro přidání dat
///
///
[HttpPost]
public void Post (hodnota řetězce [FromBody])
{
}
///
/// Vložte metodu akce pro úpravu dat
///
///
///
[HttpPut ("{id}")]
public void Put (int id, hodnota řetězce [FromBody])
{
}
///
/// Odstranit metodu akce
///
///
[HttpDelete ("{id}")]
public void Delete (int id)
{
}
}
Zapněte komentáře XML v aplikaci Swagger
Swagger ve výchozím nastavení nezobrazuje komentáře XML. Tuto funkci musíte zapnout. Chcete-li to provést, klepněte pravým tlačítkem na projekt, vyberte Vlastnosti a poté přejděte na kartu Sestavit. Na kartě Vytvořit zaškrtněte volbu „Soubor dokumentace XML“ a určete umístění, kde bude soubor dokumentace XML vytvořen.
Měli byste také určit, že komentáře XML by měly být zahrnuty při generování dokumentu Swagger napsáním následujícího kódu v metodě ConfigureServices.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
A to je vše, co musíte udělat, abyste ve Swagger zapnuli komentáře XML.
Nastavte spouštěcí adresu URL aplikace na Swagger UI
Můžete změnit adresu URL pro spuštění aplikace a určit, že při spuštění aplikace se načte uživatelské rozhraní Swagger. Chcete-li to provést, klepněte pravým tlačítkem na projekt a vyberte Vlastnosti. Poté přejděte na kartu Debug. Nakonec zadejte hodnotu Launch Browser jako swagger, jak je znázorněno na obrázku 2.
Když aplikaci znovu spustíte a přejdete na adresu Swagger URL, měli byste vidět uživatelské rozhraní Swagger, jak je znázorněno na obrázku 3 níže. Tentokrát si všimněte komentářů XML v každé z metod API.
Swashbuckle je skvělý nástroj pro generování dokumentů Swagger pro vaše API. Nejdůležitější je, že Swashbuckle se snadno konfiguruje a používá. Se Swaggerem můžete udělat mnohem více, než jsme viděli zde. Můžete přizpůsobit uživatelské rozhraní Swagger pomocí kaskádových stylů, zobrazit hodnoty výčtu jako hodnoty řetězce a vytvořit různé dokumenty Swagger pro různé verze vašeho API, abychom jmenovali alespoň některé.
