Du vil ofte gerne oprette dokumentation til din API. For at oprette denne dokumentation kan du drage fordel af Swagger - et værktøj, der let kan bruges til at give en UI-gengivelse af din API. Når du har genereret Swagger-dokumentation til din API, kan du se underskriften på dine API-metoder og endda også teste dine API-metoder.
Swashbuckle er et open source-projekt til generering af Swagger-dokumenter. Denne artikel præsenterer en diskussion af, hvordan vi kan udnytte Swashbuckle til at generere interaktiv dokumentation til vores RESTful API.
Opret et ASP.Net Core-projekt
Lad os først oprette et ASP.Net Core-projekt i Visual Studio. Forudsat at Visual Studio 2017 eller Visual Studio 2019 er installeret i dit system, skal du følge nedenstående trin for at oprette et nyt ASP.Net Core-projekt i Visual Studio.
- Start Visual Studio IDE.
- Klik på "Opret nyt projekt."
- I vinduet "Opret nyt projekt" skal du vælge "ASP.Net Core Web Application" fra listen over skabeloner, der vises.
- Klik på Næste.
- I vinduet "Konfigurer dit nye projekt", der vises derefter, skal du angive navnet og placeringen for det nye projekt.
- Klik på Opret.
- I vinduet "Opret ny ASP.Net Core-webapplikation" skal du vælge .Net Core som runtime og ASP.Net Core 2.2 (eller nyere) fra rullelisten øverst.
- Vælg “API” som projektskabelon for at oprette et nyt ASP.Net Core Web API-projekt.
- Sørg for, at afkrydsningsfelterne "Aktivér Docker-support" og "Konfigurer til HTTPS" ikke er markeret, da vi ikke bruger disse funktioner her.
- Sørg for, at godkendelse er indstillet som "Ingen godkendelse", da vi heller ikke bruger godkendelse.
- Klik på Opret.
Ved at følge disse trin oprettes et nyt ASP.Net Core-projekt i Visual Studio. Vi bruger dette projekt i de efterfølgende afsnit i denne artikel til at undersøge, hvordan vi kan generere Swagger-dokumentation til ValuesController.
Installer Swagger middleware i ASP.Net Core
Hvis du har oprettet et ASP.Net Core-projekt med succes, er den næste ting du skal gøre, at tilføje de nødvendige NuGet-pakker til dit projekt. For at gøre dette skal du vælge projektet i vinduet Solution Explorer, højreklikke og vælge “Manage NuGet Packages ....” I vinduet NuGet Package Manager skal du søge efter pakken Swashbuckle.AspNetCore og installere den. Alternativt kan du installere pakken via NuGet Package Manager Console som vist nedenfor.
PM> Installationspakke Swashbuckle.AspNetCore
Swashbuckle.AspNetCore-pakken indeholder de nødvendige værktøjer til at generere API-dokumenter til ASP.Net Core.
Konfigurer Swagger middleware i ASP.Net Core
For at konfigurere Swagger skal du skrive følgende kode i metoden ConfigureServices. Bemærk, hvordan AddSwaggerGen-udvidelsesmetoden bruges til at specificere metadataene til API-dokumentet.
services.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", ny info
{
Version = "v1",
Titel = "Swagger Demo",
Beskrivelse = "Swagger Demo for ValuesController",
TermsOfService = "Ingen",
Kontakt = ny kontakt () {Navn = "Joydip Kanjilal",
E-mail = "[email protected]",
Url = "www.google.com"}
});
});
Du bør også aktivere Swagger UI i konfigurationsmetoden som vist nedenfor.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Her er den komplette kode for Startup-klassen til din reference.
ved hjælp af Microsoft.AspNetCore.Builder;ved hjælp af Microsoft.AspNetCore.Hosting;
ved hjælp af Microsoft.AspNetCore.Mvc;
ved hjælp af Microsoft.Extensions.Configuration;
ved hjælp af Microsoft.Extensions.DependencyInjection;
ved hjælp af Swashbuckle.AspNetCore.Swagger;
navneområde SwaggerDemo
{
offentlig klasse opstart
{
offentlig opstart (konfiguration af IConfiguration)
{
Konfiguration = konfiguration;
}
offentlig IConfiguration Configuration {get; }
offentlig ugyldighed ConfigureServices (IServiceCollection-tjenester)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", ny info
{
Version = "v1",
Titel = "Swagger Demo",
Beskrivelse = "Swagger Demo for ValuesController",
TermsOfService = "Ingen",
Kontakt = ny kontakt () {Navn = "Joydip Kanjilal",
E-mail = "[email protected]",
Url = "www.google.com"
}
});
});
}
public void Configure (IApplicationBuilder app,
IHostingEnvironment env)
{
hvis (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
Dette er alt hvad du skal gøre for at komme i gang med Swagger.
Gennemse Swagger UI i din ASP.Net Core-app
Nu er vi klar til at udføre applikationen og gennemse Swagger-slutpunktet. Swagger UI vises som i figur 1 nedenfor. Bemærk, hvordan Swagger bruger forskellige farver til HTTP-verberne GET, PUT, POST og SLET. Du kan udføre hvert af slutpunkterne vist i figur 1 direkte fra Swagger UI.
Opret XML-kommentarer i din controllerens handlingsmetoder
Så langt så godt. I Swagger-dokumentet, der blev genereret tidligere, var der ingen XML-kommentarer. Hvis du vil vise XML-kommentarer i Swagger-dokumentet, skal du blot skrive disse kommentarer i din controllerens handlingsmetoder.
Lad os nu skrive kommentarer til hver af handlingsmetoderne i ValuesController. Her er den opdaterede version af ValuesController med XML-kommentarer til hver af handlingsmetoderne.
[Rute ("api / [controller]")] [ApiController]
public class ValuesController: ControllerBase
{
///
/// Få handlingsmetode uden noget argument
///
///
[HttpGet]
offentlig ActionResult Få() {
returner ny streng [] {"værdi1", "værdi2"};
}
///
/// Få handlingsmetode, der accepterer et heltal som et argument
///
///
///
[HttpGet ("{id}")]
offentlig ActionResult Get (int id)
{
returner "værdi";
}
///
/// Post handlingsmetode for at tilføje data
///
///
[HttpPost]
offentlig ugyldig Post ([FromBody] strengværdi)
{
}
///
/// Sæt handlingsmetode for at ændre data
///
///
///
[HttpPut ("{id}")]
public void Put (int id, [FromBody] strengværdi)
{
}
///
/// Slet handlingsmetode
///
///
[HttpDelete ("{id}")]
offentlig tomrum Slet (int id)
{
}
}
Slå XML-kommentarer til i Swagger
Bemærk, at Swagger ikke viser XML-kommentarer som standard. Du skal aktivere denne funktion. For at gøre dette skal du højreklikke på Project, vælge Egenskaber og derefter navigere til fanen Build. På fanen Build skal du kontrollere "XML-dokumentationsfil" for at angive det sted, hvor XML-dokumentationsfilen oprettes.
Du skal også angive, at XML-kommentarer skal medtages, når du genererer Swagger-dokumentet ved at skrive følgende kode i ConfigureServices-metoden.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
Og det er alt hvad du skal gøre for at slå XML-kommentarer til i Swagger.
Indstil startwebadressen til appen til Swagger UI
Du kan ændre din applikations start-URL for at angive, at Swagger UI indlæses, når applikationen startes. For at gøre dette skal du højreklikke på Projekt og vælge Egenskaber. Naviger derefter til fanen Debug. Til sidst skal du angive Launch Browser-værdien som swagger som vist i figur 2.
Når du kører applikationen igen og navigerer til Swagger URL, skal du se Swagger UI som vist i figur 3 nedenfor. Bemærk XML-kommentarerne i hver af API-metoderne denne gang.
Swashbuckle er et fantastisk værktøj til at generere Swagger-dokumenter til din API. Vigtigst er det, at Swashbuckle er let at konfigurere og bruge. Der er meget mere, du kan gøre med Swagger, end vi har set her. Du kan tilpasse Swagger UI ved hjælp af Cascading Style Sheets, vise enumværdier som strengværdier og oprette forskellige Swagger-dokumenter til forskellige versioner af din API, for bare at nævne nogle få.
