Jūs bieži vēlaties izveidot dokumentāciju savai API. Lai izveidotu šo dokumentāciju, varat izmantot Swagger priekšrocības - rīku, ko var izmantot, lai viegli nodrošinātu API saskarni UI. Kad esat izveidojis Swagger dokumentāciju savai API, varat skatīt savu API metožu parakstu un pat pārbaudīt arī API metodes.
Swashbuckle ir atvērtā pirmkoda projekts Swagger dokumentu ģenerēšanai. Šis raksts piedāvā diskusiju par to, kā mēs varam izmantot Swashbuckle priekšrocības, lai ģenerētu interaktīvu dokumentāciju mūsu RESTful API.
Izveidojiet ASP.Net Core projektu
Vispirms izveidosim ASP.Net Core projektu Visual Studio. Pieņemot, ka Visual Studio 2017 vai Visual Studio 2019 ir instalēta jūsu sistēmā, veiciet tālāk norādītās darbības, lai izveidotu jaunu ASP.Net Core projektu Visual Studio.
- Palaidiet Visual Studio IDE.
- Noklikšķiniet uz “Izveidot jaunu projektu”.
- Logā “Izveidot jaunu projektu” parādīto veidņu sarakstā atlasiet “ASP.Net Core Web Application”.
- Noklikšķiniet uz Tālāk.
- Nākamajā logā “Konfigurēt jauno projektu” norādiet jaunā projekta nosaukumu un vietu.
- Noklikšķiniet uz Izveidot.
- Logā “Izveidot jaunu ASP.Net Core tīmekļa lietojumprogrammu” augšdaļā esošajā nolaižamajā sarakstā atlasiet .Net Core kā izpildlaiku un ASP.Net Core 2.2 (vai jaunāku).
- Atlasiet “API” kā projekta veidni, lai izveidotu jaunu ASP.Net Core Web API projektu.
- Pārliecinieties, vai nav atzīmētas izvēles rūtiņas “Iespējot Docker atbalstu” un “Konfigurēt HTTPS”, jo mēs šeit neizmantosim šīs funkcijas.
- Pārliecinieties, ka autentifikācija ir iestatīta kā “Nav autentifikācijas”, jo mēs arī neizmantosim autentifikāciju.
- Noklikšķiniet uz Izveidot.
Veicot šīs darbības, Visual Studio tiks izveidots jauns ASP.Net Core projekts. Mēs izmantosim šo projektu šī raksta nākamajās sadaļās, lai pārbaudītu, kā mēs varam ģenerēt Swagger dokumentāciju ValuesController.
Instalējiet Swagger starpprogrammatūru ASP.Net Core
Ja esat veiksmīgi izveidojis ASP.Net Core projektu, nākamais, kas jums jādara, ir jāpievieno projektam nepieciešamās NuGet paketes. Lai to izdarītu, logā Solution Explorer atlasiet projektu, ar peles labo pogu noklikšķiniet un atlasiet “Manage NuGet Packages ...”. Logā NuGet Package Manager meklējiet pakotni Swashbuckle.AspNetCore un instalējiet to. Varat arī pakotni instalēt, izmantojot NuGet Package Manager Console, kā parādīts zemāk.
PM> Install-Package Swashbuckle.AspNetCore
Swashbuckle.AspNetCore pakotne satur nepieciešamos rīkus API dokumentu ģenerēšanai ASP.Net Core.
Konfigurējiet Swagger starpprogrammatūru ASP.Net Core
Lai konfigurētu Swagger, ierakstiet šo kodu ConfigureServices metodē. Ņemiet vērā, kā paplašinājuma AddSwaggerGen metode tiek izmantota, lai norādītu API dokumenta metadatus.
services.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", jauna informācija
{
Versija = "v1",
Nosaukums = "Swagger Demo",
Description = "ValuesController paraugdemonstrējums",
TermsOfService = "Nav",
Kontaktpersona = jauns kontakts () {Name = "Joydip Kanjilal",
E-pasts = "[email protected]",
URL = "www.google.com"}
});
});
Jums vajadzētu arī iespējot Swagger UI konfigurēšanas metodē, kā parādīts zemāk.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Šeit ir pilns Startup klases kods jūsu atsaucei.
izmantojot Microsoft.AspNetCore.Builder;izmantojot Microsoft.AspNetCore.Hosting;
izmantojot Microsoft.AspNetCore.Mvc;
izmantojot Microsoft.Extensions.Configuration;
izmantojot Microsoft.Extensions.DependencyInjection;
izmantojot Swashbuckle.AspNetCore.Swagger;
nosaukumvieta SwaggerDemo
{
publiskā klase Startup
{
publiskā startēšana (ICkonfigurācijas konfigurācija)
{
Konfigurācija = konfigurācija;
}
publiskā ICkonfigurācijas konfigurācija {get; }
public void ConfigureServices (IServiceCollection pakalpojumi)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", jauna informācija
{
Versija = "v1",
Nosaukums = "Swagger Demo",
Description = "ValuesController paraugdemonstrējums",
TermsOfService = "Nav",
Kontaktpersona = jauns kontakts () {Name = "Joydip Kanjilal",
E-pasts = "[email protected]",
URL = "www.google.com"
}
});
});
}
public void Configure (lietotne IApplicationBuilder,
IHostingVides vide)
{
ja (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
Tas ir viss, kas jums jādara, lai sāktu darbu ar Swagger.
Pārlūkojiet savas ASP.Net Core lietotnes Swagger lietotāja saskarni
Tagad mēs esam gatavi izpildīt lietojumprogrammu un pārlūkot Swagger galapunktu. Parādīsies Swagger lietotāja interfeiss, kā parādīts 1. attēlā. Ievērojiet, kā Swagger izmanto dažādas krāsas HTTP darbības vārdiem GET, PUT, POST un DELETE. Katru no 1. attēlā parādītajiem galapunktiem var izpildīt tieši no Swagger lietotāja saskarnes.
Izveidojiet XML komentārus kontroliera darbības metodēs
Tik tālu, labi. Iepriekš izveidotajā Swagger dokumentā nebija XML komentāru. Ja vēlaties parādīt XML komentārus Swagger dokumentā, vienkārši ierakstiet šos komentārus kontroliera darbības metodēs.
Tagad rakstīsim komentārus par katru no darbības metodēm ValuesController. Šeit ir atjaunināta ValuesController versija ar XML komentāriem katrai darbības metodei.
[Maršruts ("api / [kontrolieris]")] [ApiController]
public class ValuesController: ControllerBase
{
///
/// Iegūt darbības metodi bez jebkāda argumenta
///
///
[HttpGet]
publisks ActionResult Gūt() {
atgriezt jaunu virkni [] {"value1", "value2"};
}
///
/// Iegūt darbības metodi, kas par argumentu pieņem veselu skaitli
///
///
///
[HttpGet ("{id}")]
public ActionResult Get (int id)
{
atgriešanās "vērtība";
}
///
/// Publicējiet darbības metodi, lai pievienotu datus
///
///
[HttpPost]
public void Post (virknes vērtība [FromBody])
{
}
///
/// Put action metode datu modificēšanai
///
///
///
[HttpPut ("{id}")]
public void Put (int id, [FromBody] virknes vērtība)
{
}
///
/// Dzēst darbības metodi
///
///
[HttpDelete ("{id}")]
public void Dzēst (int id)
{
}
}
Ieslēdziet XML komentārus vietnē Swagger
Ņemiet vērā, ka Swagger pēc noklusējuma neparāda XML komentārus. Jums ir jāieslēdz šī funkcija. Lai to izdarītu, ar peles labo pogu noklikšķiniet uz Project, atlasiet Properties un pēc tam pārejiet uz cilni Build. Cilnē Izveidot atzīmējiet opciju “XML dokumentācijas fails”, lai norādītu vietu, kur tiks izveidots XML dokumentācijas fails.
Jums arī jānorāda, ka XML komentāri jāiekļauj, ģenerējot Swagger dokumentu, ierakstot šādu kodu ConfigureServices metodē.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
Tas ir viss, kas jums jādara, lai Swagger ieslēgtu XML komentārus.
Iestatiet lietotnes palaišanas URL uz Swagger UI
Varat mainīt lietojumprogrammas palaišanas URL, lai norādītu, ka Swagger lietotāja saskarne tiks ielādēta, kad programma tiks palaista. Lai to izdarītu, ar peles labo pogu noklikšķiniet uz Project un atlasiet Properties. Pēc tam pārejiet uz cilni Atkļūdošana. Visbeidzot, norādiet Launch Browser vērtību kā svārstīgu, kā parādīts 2. attēlā.
Atkārtoti palaižot lietojumprogrammu un dodoties uz vietni Swagger URL, jums vajadzētu redzēt Swagger lietotāja saskarni, kā parādīts 3. attēlā. Šoreiz ņemiet vērā XML komentārus katrā no API metodēm.
Swashbuckle ir lielisks rīks Swagger dokumentu ģenerēšanai jūsu API. Vissvarīgākais ir tas, ka Swashbuckle ir viegli konfigurējams un lietojams. Ar Swagger var darīt daudz vairāk, nekā mēs šeit esam redzējuši. Jūs varat pielāgot Swagger lietotāja interfeisu, izmantojot kaskādes stila lapas, parādīt uzskaites vērtības kā virknes vērtības un izveidot dažādus Swagger dokumentus dažādām jūsu API versijām, lai tikai nosauktu dažus.
