Haluat usein luoda dokumentaatiota sovellusliittymällesi. Voit luoda tämän dokumentaation hyödyntämällä Swaggeria - työkalua, jota voidaan käyttää tarjoamaan sovellusliittymän käyttöliittymäesitys helposti. Kun olet luonut Swagger-dokumentaation API: lle, voit tarkastella API-menetelmien allekirjoitusta ja jopa testata API-menetelmiäsi.
Swashbuckle on avoimen lähdekoodin projekti Swagger-dokumenttien luomiseen. Tässä artikkelissa käsitellään sitä, miten voimme hyödyntää Swashbucklea interaktiivisen dokumentaation luomiseksi RESTful-sovellusliittymällemme.
Luo ASP.Net-ydinprojekti
Ensinnäkin, luodaan ASP.Net Core -projekti Visual Studiossa. Olettaen, että Visual Studio 2017 tai Visual Studio 2019 on asennettu järjestelmään, luo uusi ASP.Net Core -projekti Visual Studiossa noudattamalla seuraavia ohjeita.
- Käynnistä Visual Studio IDE.
- Napsauta Luo uusi projekti.
- Valitse Luo uusi projekti -ikkunassa ”ASP.Net Core Web Application” näytetystä mallipohjaluettelosta.
- Napsauta Seuraava.
- Määritä seuraavan projektin nimi ja sijainti seuraavassa "Määritä uusi projekti" -ikkunassa.
- Napsauta Luo.
- Valitse Luo uusi ASP.Net Core Web -sovellus -ikkunassa .Net Core ajonaikaiseksi ja ASP.Net Core 2.2 (tai uudempi) ylhäältä avattavasta luettelosta.
- Luo uusi ASP.Net Core Web API -projekti valitsemalla projektimalliksi “API”.
- Varmista, että valintaruudut Ota Docker-tuki käyttöön ja Määritä HTTPS: lle ei ole valittu, koska emme käytä näitä ominaisuuksia täällä.
- Varmista, että todennukseksi on määritetty Ei todentamista, koska emme myöskään käytä todennusta.
- Napsauta Luo.
Näiden vaiheiden seuraaminen luo uuden ASP.Net Core -projektin Visual Studioon. Käytämme tätä projektia tämän artikkelin seuraavissa osioissa tutkiakseen, miten voimme luoda Swagger-dokumentaation ValuesControllerille.
Asenna Swagger-väliohjelmisto ASP.Net Core -ohjelmaan
Jos olet onnistuneesti luonut ASP.Net Core -projektin, seuraava asia, jonka sinun pitäisi tehdä, on lisätä tarvittavat NuGet-paketit projektiisi. Voit tehdä tämän valitsemalla projektin Solution Explorer -ikkunassa, napsauttamalla hiiren kakkospainikkeella ja valitsemalla "Manage NuGet Packages ....". NuGet Package Manager -ikkunassa etsi paketti Swashbuckle.AspNetCore ja asenna se. Vaihtoehtoisesti voit asentaa paketin NuGet Package Manager -konsolin kautta alla olevan kuvan mukaisesti.
PM> Install-Package Swashbuckle.AspNetCore
Swashbuckle.AspNetCore-paketti sisältää tarvittavat työkalut API-asiakirjojen luomiseen ASP.Net Core -sovellukselle.
Määritä Swagger-väliohjelmisto ASP.Net Core -sovelluksessa
Määritä Swagger kirjoittamalla seuraava koodi ConfigureServices-menetelmään. Huomaa, kuinka AddSwaggerGen-laajennusmenetelmää käytetään määrittämään API-asiakirjan metatiedot.
services.AddSwaggerGen (c =>{
c.SwaggerDoc ("v1", uusi tieto
{
Versio = "v1",
Otsikko = "Swagger Demo",
Description = "Swagger-esittely ValuesControllerille",
TermsOfService = "Ei mitään",
Yhteystieto = uusi yhteyshenkilö () {Name = "Joydip Kanjilal",
Email = "[email protected]",
URL = "www.google.com"}
});
});
Ota myös käyttöön Swagger UI Configure -menetelmässä alla esitetyllä tavalla.
app.UseSwagger ();app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
Tässä on Startup-luokan täydellinen koodi viitteellesi.
käyttämällä Microsoft.AspNetCore.Builder;käyttämällä Microsoft.AspNetCore.Hosting;
käyttämällä Microsoft.AspNetCore.Mvc;
käyttämällä Microsoft.Extensions.Configuration;
käyttämällä Microsoft.Extensions.DependencyInjection;
käyttämällä Swashbuckle.AspNetCore.Swagger;
nimitila SwaggerDemo
{
julkisen luokan käynnistys
{
julkinen käynnistys (IConfiguration configuration)
{
Kokoonpano = kokoonpano;
}
julkinen IConfiguration Configuration {get; }
public void ConfigureServices (IServiceCollection-palvelut)
{
services.AddMvc (). SetCompatibilityVersion
(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen (c =>
{
c.SwaggerDoc ("v1", uusi tieto
{
Versio = "v1",
Otsikko = "Swagger Demo",
Description = "Swagger-esittely ValuesControllerille",
TermsOfService = "Ei mitään",
Yhteystieto = uusi yhteyshenkilö () {Name = "Joydip Kanjilal",
Email = "[email protected]",
URL = "www.google.com"
}
});
});
}
public void Määritä (IApplicationBuilder-sovellus,
IHostingEnvironment env)
{
if (env.IsDevelopment ())
{
app.UseDeveloperExceptionPage ();
}
app.UseMvc ();
app.UseSwagger ();
app.UseSwaggerUI (c =>
{
c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");
});
}
}
}
Tämä on kaikki mitä sinun on tehtävä aloittaaksesi Swaggerin käytön.
Selaa ASP.Net Core -sovelluksesi Swagger-käyttöliittymää
Nyt olemme valmiita suorittamaan sovelluksen ja selaamaan Swagger-päätepistettä. Swagger-käyttöliittymä ilmestyy kuten alla olevassa kuvassa 1. Huomaa, kuinka Swagger käyttää eri värejä HTTP-verbeihin GET, PUT, POST ja DELETE. Voit suorittaa kaikki kuvassa 1 esitetyt päätepisteet suoraan Swagger-käyttöliittymästä.
Luo XML-kommentteja ohjaimen toimintamenetelmissä
Toistaiseksi niin hyvä. Aikaisemmin luotussa Swagger-asiakirjassa ei ollut XML-kommentteja. Jos haluat näyttää XML-kommentteja Swagger-asiakirjassa, kirjoita nämä kommentit vain ohjaimesi toimintatapoihin.
Kirjoita nyt kommentit jokaiselle toimintatavalle ValuesControlleriin. Tässä on päivitetty ValuesController-versio, joka sisältää XML-kommentit jokaiselle toimintatavalle.
[Reitti ("api / [ohjain]")][ApiController]
public class ValuesController: ControllerBase
{
///
/// Hanki toimintamenetelmä ilman argumentteja
///
///
[HttpGet]
julkinen toimintatulos
Saada() {
palauta uusi merkkijono [] {"arvo1", "arvo2"};
}
///
/// Hae toimintamenetelmä, joka hyväksyy kokonaisluvun argumenttina
///
///
///
[HttpGet ("{id}")]
public ActionResult Get (int id)
{
return "arvo";
}
///
/// Lisää toiminto menetelmän avulla
///
///
[HttpPost]
public void Post ([FromBody] merkkijonoarvo)
{
}
///
/// Laita toimintatapa tietojen muokkaamiseksi
///
///
///
[HttpPut ("{id}")]
public void Put (int id, [FromBody] merkkijonoarvo)
{
}
///
/// Poista toimintamenetelmä
///
///
[HttpDelete ("{id}")]
public void Poista (int id)
{
}
}
Ota XML-kommentit käyttöön Swaggerissa
Huomaa, että Swagger ei näytä XML-kommentteja oletuksena. Sinun on otettava tämä ominaisuus käyttöön. Voit tehdä tämän napsauttamalla hiiren kakkospainikkeella Project, valitsemalla Properties ja siirtymällä sitten Build-välilehdelle. Määritä Rakennus-välilehden XML-dokumenttitiedosto -vaihtoehto paikka, johon XML-dokumenttitiedosto luodaan.
Sinun on myös määritettävä, että XML-kommentit tulisi sisällyttää Swagger-asiakirjaa luodessa kirjoittamalla seuraava koodi ConfigureServices-menetelmään.
c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");
Ja kaikki, mitä sinun tarvitsee tehdä, jotta XML-kommentit otetaan käyttöön Swaggerissa.
Aseta sovelluksen käynnistysosoitteeksi Swagger UI
Voit muuttaa sovelluksen käynnistysosoitetta ja määrittää, että Swagger-käyttöliittymä ladataan, kun sovellus käynnistetään. Voit tehdä tämän napsauttamalla hiiren kakkospainikkeella Projektia ja valitsemalla Ominaisuudet. Siirry sitten Debug-välilehteen. Määritä lopuksi Käynnistysselain-arvo vaihtelevana kuvan 2 mukaisesti.
Kun suoritat sovelluksen uudelleen ja siirryt Swagger-URL-osoitteeseen, sinun pitäisi nähdä Swagger-käyttöliittymä alla olevan kuvan 3 mukaisesti. Huomaa XML-kommentit kussakin API-menetelmässä tällä kertaa.
Swashbuckle on loistava työkalu Swagger-asiakirjojen luomiseen sovellusliittymällesi. Mikä tärkeintä, Swashbuckle on helppo konfiguroida ja käyttää. Swaggerilla voi tehdä paljon enemmän kuin mitä olemme nähneet täällä. Voit mukauttaa Swagger-käyttöliittymää käyttämällä CSS-tyylitaulukoita, näyttää enum-arvot merkkijonoarvoina ja luoda erilaisia Swagger-asiakirjoja sovellusliittymän eri versioille vain muutamia mainitakseni.