Ohjelmointi

Kuinka käyttää Swaggeria ASP.Net Core -sovelluksessa

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.

  1. Käynnistä Visual Studio IDE.
  2. Napsauta Luo uusi projekti.
  3. Valitse Luo uusi projekti -ikkunassa ”ASP.Net Core Web Application” näytetystä mallipohjaluettelosta.
  4. Napsauta Seuraava.
  5. Määritä seuraavan projektin nimi ja sijainti seuraavassa "Määritä uusi projekti" -ikkunassa.
  6. Napsauta Luo.
  7. Valitse Luo uusi ASP.Net Core Web -sovellus -ikkunassa .Net Core ajonaikaiseksi ja ASP.Net Core 2.2 (tai uudempi) ylhäältä avattavasta luettelosta.
  8. Luo uusi ASP.Net Core Web API -projekti valitsemalla projektimalliksi “API”.
  9. 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ä.
  10. Varmista, että todennukseksi on määritetty Ei todentamista, koska emme myöskään käytä todennusta.
  11. 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.