Du vil ofte lage dokumentasjon for API-en. For å opprette denne dokumentasjonen kan du dra nytte av Swagger - et verktøy som enkelt kan brukes til å gi en UI-representasjon av API-en. Når du har generert Swagger-dokumentasjon for API-en din, kan du se signaturen til API-metodene dine og til og med teste API-metodene dine også.
Swashbuckle er et open source-prosjekt for å generere Swagger-dokumenter. Denne artikkelen presenterer en diskusjon om hvordan vi kan dra nytte av Swashbuckle for å generere interaktiv dokumentasjon for vårt RESTful API.
Opprett et ASP.Net Core-prosjekt
Først og fremst, la oss lage et ASP.Net Core-prosjekt i Visual Studio. Forutsatt at Visual Studio 2017 eller Visual Studio 2019 er installert i systemet ditt, følger du trinnene som er beskrevet nedenfor for å opprette et nytt ASP.Net Core-prosjekt i Visual Studio.
- Start Visual Studio IDE.
- Klikk på "Opprett nytt prosjekt."
- I vinduet "Opprett nytt prosjekt" velger du "ASP.Net Core Web Application" fra listen over maler som vises.
- Klikk på Neste.
- I vinduet "Konfigurer ditt nye prosjekt" som vises neste, spesifiserer du navnet og stedet for det nye prosjektet.
- Klikk på Opprett.
- I vinduet "Create New ASP.Net Core Web Application" velger du .Net Core som kjøretid og ASP.Net Core 2.2 (eller nyere) fra rullegardinlisten øverst.
- Velg “API” som prosjektmal for å opprette et nytt ASP.Net Core Web API-prosjekt.
- Forsikre deg om at avmerkingsboksene "Aktiver Docker-støtte" og "Konfigurer for HTTPS" ikke er merket av da vi ikke bruker disse funksjonene her.
- Forsikre deg om at autentisering er angitt som “ingen godkjenning”, da vi heller ikke bruker autentisering.
- Klikk på Opprett.
Ved å følge disse trinnene opprettes et nytt ASP.Net Core-prosjekt i Visual Studio. Vi vil bruke dette prosjektet i de påfølgende delene av denne artikkelen for å undersøke hvordan vi kan generere Swagger-dokumentasjon for ValuesController.
Installer Swagger mellomvare i ASP.Net Core
Hvis du har opprettet et ASP.Net Core-prosjekt, er det neste du bør gjøre å legge til de nødvendige NuGet-pakkene i prosjektet ditt. For å gjøre dette, velg prosjektet i Solution Explorer-vinduet, høyreklikk og velg "Manage NuGet Packages ...." I NuGet Package Manager-vinduet, søk etter pakken Swashbuckle.AspNetCore og installer den. Alternativt kan du installere pakken via NuGet Package Manager-konsollen som vist nedenfor.
PM> Installasjonspakke Swashbuckle.AspNetCore
Swashbuckle.AspNetCore-pakken inneholder de nødvendige verktøyene for å generere API-dokumenter for ASP.Net Core.
Konfigurer Swagger mellomvare i ASP.Net Core
For å konfigurere Swagger, skriv følgende kode i ConfigureServices-metoden. Legg merke til hvordan AddSwaggerGen-utvidelsesmetoden brukes til å spesifisere metadataene for API-dokumentet.
services.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", ny info
{
Versjon = "v1",
Tittel = "Swagger Demo",
Beskrivelse = "Swagger Demo for ValuesController",
TermsOfService = "Ingen",
Kontakt = ny kontakt () {Name = "Joydip Kanjilal",
E-post = "[email protected]",
Url = "www.google.com"}
});
});
Du bør også aktivere Swagger UI i konfigurasjonsmetoden som vist nedenfor.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Her er den fullstendige koden til oppstartsklassen som referanse.
ved hjelp av Microsoft.AspNetCore.Builder;ved hjelp av Microsoft.AspNetCore.Hosting;
ved hjelp av Microsoft.AspNetCore.Mvc;
ved hjelp av Microsoft.Extensions.Configuration;
ved hjelp av Microsoft.Extensions.DependencyInjection;
ved hjelp av Swashbuckle.AspNetCore.Swagger;
navnerom SwaggerDemo
{
offentlig klasse Oppstart
{
offentlig oppstart (konfigurasjon av IConfiguration)
{
Konfigurasjon = konfigurasjon;
}
offentlig IConfiguration Configuration {get; }
offentlig ugyldighet ConfigureServices (IServiceCollection-tjenester)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", ny info
{
Versjon = "v1",
Tittel = "Swagger Demo",
Beskrivelse = "Swagger Demo for ValuesController",
TermsOfService = "Ingen",
Kontakt = ny kontakt () {Name = "Joydip Kanjilal",
E-post = "[email protected]",
URL = "www.google.com"
}
});
});
}
public void Configure (IApplicationBuilder app,
IHostingEnvironment env)
{
if (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
Dette er alt du trenger å gjøre for å komme i gang med Swagger.
Bla gjennom Swagger UI i ASP.Net Core-appen
Nå er vi klare til å utføre applikasjonen og bla gjennom Swagger-endepunktet. Brukergrensesnittet til Swagger vil vises som i figur 1 nedenfor. Legg merke til hvordan Swagger bruker forskjellige farger for HTTP-verbene GET, PUT, POST og DELETE. Du kan utføre hvert av endepunktene vist i figur 1 direkte fra Swagger UI.
Lag XML-kommentarer i kontrollerens handlingsmetoder
Så langt så bra. I Swagger-dokumentet generert tidligere var det ingen XML-kommentarer. Hvis du vil vise XML-kommentarer i Swagger-dokumentet, skriver du bare kommentarene i kontrollerens handlingsmetoder.
La oss nå skrive kommentarer for hver av handlingsmetodene i ValuesController. Her er den oppdaterte versjonen av ValuesController med XML-kommentarer for hver av handlingsmetodene.
[Rute ("api / [controller]")] [ApiController]
offentlig klasse ValuesController: ControllerBase
{
///
/// Få handlingsmetode uten noe argument
///
///
[HttpGet]
offentlig ActionResult Få() {
returner ny streng [] {"value1", "value2"};
}
///
/// Få handlingsmetode som godtar et heltall som et argument
///
///
///
[HttpGet ("{id}")]
offentlig ActionResult Get (int id)
{
returner "verdi";
}
///
/// Legg ut handlingsmetode for å legge til data
///
///
[HttpPost]
public void Post ([FromBody] strengverdi)
{
}
///
/// Sett handlingsmetode for å endre data
///
///
///
[HttpPut ("{id}")]
offentlig ugyldig Put (int id, [FromBody] strengverdi)
{
}
///
/// Slett handlingsmetode
///
///
[HttpDelete ("{id}")]
public void Delete (int id)
{
}
}
Slå på XML-kommentarer i Swagger
Merk at Swagger ikke viser XML-kommentarer som standard. Du må slå på denne funksjonen. For å gjøre dette høyreklikker du på Prosjekt, velger Egenskaper og naviger deretter til kategorien Bygg. I kategorien Bygg sjekker du "XML-dokumentasjonsfil" for å spesifisere stedet der XML-dokumentasjonsfilen skal opprettes.
Du bør også spesifisere at XML-kommentarene skal inkluderes når du genererer Swagger-dokumentet ved å skrive følgende kode i ConfigureServices-metoden.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
Og det er alt du trenger å gjøre for å slå på XML-kommentarer i Swagger.
Sett lanserings-URL for appen til Swagger UI
Du kan endre programmets lanserings-URL for å spesifisere at Swagger UI skal lastes inn når applikasjonen startes. For å gjøre dette, høyreklikk på Project og velg Properties. Naviger deretter til Debug-fanen. Til slutt, spesifiser Launch Browser-verdien som swagger som vist i figur 2.
Når du kjører applikasjonen igjen og navigerer til Swagger URL, bør du se Swagger UI som vist i figur 3 nedenfor. Legg merke til XML-kommentarene i hver av API-metodene denne gangen.
Swashbuckle er et flott verktøy for å generere Swagger-dokumenter for API-en din. Viktigst, Swashbuckle er enkel å konfigurere og bruke. Det er mye mer du kan gjøre med Swagger enn vi har sett her. Du kan tilpasse Swagger-brukergrensesnittet ved hjelp av Cascading Style Sheets, vise enumverdier som strengverdier, og lage forskjellige Swagger-dokumenter for forskjellige versjoner av API-en din, bare for å nevne noen.
