Programiranje

Kako uporabljati Swagger v ASP.Net Core

Pogosto boste želeli ustvariti dokumentacijo za svoj API. Če želite ustvariti to dokumentacijo, lahko izkoristite Swagger - orodje, s katerim lahko z lahkoto zagotovite predstavitev uporabniškega vmesnika vašega API-ja. Ko za svoj API ustvarite dokumentacijo Swagger, si lahko ogledate podpis svojih metod API in celo preizkusite tudi svoje API-je.

Swashbuckle je odprtokodni projekt za ustvarjanje dokumentov Swagger. Ta članek predstavlja razpravo o tem, kako lahko Swashbuckle izkoristimo za ustvarjanje interaktivne dokumentacije za naš API RESTful.

Ustvarite projekt ASP.Net Core

Najprej ustvarimo projekt ASP.Net Core v Visual Studio. Če predpostavimo, da je Visual Studio 2017 ali Visual Studio 2019 nameščen v vašem sistemu, sledite spodnjim korakom, da ustvarite nov projekt ASP.Net Core v Visual Studio.

  1. Zaženite Visual Studio IDE.
  2. Kliknite »Ustvari nov projekt«.
  3. V oknu »Ustvari nov projekt« na seznamu predlog izberite »ASP.Net Core Web Application«.
  4. Kliknite Naprej.
  5. V oknu »Konfiguriranje novega projekta«, ki je prikazano naslednje, navedite ime in mesto novega projekta.
  6. Kliknite Ustvari.
  7. V oknu »Ustvari novo spletno aplikacijo ASP.Net Core« izberite .Net Core kot izvajalno okolje in ASP.Net Core 2.2 (ali novejšo) s spustnega seznama na vrhu.
  8. Kot predlogo projekta izberite »API«, da ustvarite nov projekt ASP.Net Core Web API.
  9. Prepričajte se, da sta potrditveni polji »Omogoči podporo za Docker« in »Konfiguriranje za HTTPS« odstranjeni, saj tukaj ne bomo uporabljali teh funkcij.
  10. Prepričajte se, da je preverjanje pristnosti nastavljeno na »Brez preverjanja pristnosti«, saj tudi preverjanja pristnosti ne bomo uporabljali.
  11. Kliknite Ustvari.

Po teh korakih boste v Visual Studio ustvarili nov projekt ASP.Net Core. Ta projekt bomo uporabili v naslednjih odsekih tega članka, da bomo preučili, kako lahko ustvarimo Swaggerjevo dokumentacijo za ValuesController.

Namestite vmesno programsko opremo Swagger v ASP.Net Core

Če ste uspešno ustvarili projekt ASP.Net Core, morate v svoj projekt dodati potrebne pakete NuGet. Če želite to narediti, izberite projekt v oknu raziskovalca rešitev, z desno miškino tipko kliknite in izberite »Upravljanje paketov NuGet ....« V oknu Upravitelja paketov NuGet poiščite paket Swashbuckle.AspNetCore in ga namestite. Paket lahko namestite tudi prek konzole NuGet Package Manager, kot je prikazano spodaj.

PM> Swashbuckle.AspNetCore

Paket Swashbuckle.AspNetCore vsebuje potrebna orodja za ustvarjanje dokumentov API za ASP.Net Core.

Konfigurirajte vmesno programsko opremo Swagger v ASP.Net Core

Če želite konfigurirati Swagger, v metodo ConfigureServices napišite naslednjo kodo. Upoštevajte, kako se metoda razširitve AddSwaggerGen uporablja za določanje metapodatkov za dokument API.

storitve.AddSwaggerGen (c =>

            {

c.SwaggerDoc ("v1", nove informacije

                {

Različica = "v1",

Naslov = "Swagger Demo",

Opis = "Swagger Demo for ValuesController",

TermsOfService = "Brez",

Stik = nov stik () {Name = "Joydip Kanjilal",

E-pošta = "[email protected]",

Url = "www.google.com"}

                });

            });

Prav tako morate omogočiti uporabniški vmesnik Swagger v metodi Konfiguriranje, kot je prikazano spodaj.

app.UseSwagger ();

app.UseSwaggerUI (c =>

{

c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

});

Tu je celotna koda zagonskega razreda za vašo referenco.

z uporabo Microsoft.AspNetCore.Builder;

z uporabo Microsoft.AspNetCore.Hosting;

z uporabo Microsoft.AspNetCore.Mvc;

z uporabo Microsoft.Extensions.Configuration;

z uporabo Microsoft.Extensions.DependencyInjection;

z uporabo Swashbuckle.AspNetCore.Swagger;

imenski prostor SwaggerDemo

{

javni razred Startup

    {

javni zagon (konfiguracija IConfiguration)

        {

Konfiguracija = konfiguracija;

        }

javna konfiguracija IConfiguration {get; }

public void ConfigureServices (storitve IServiceCollection)

        {

services.AddMvc (). SetCompatibilityVersion

(CompatibilityVersion.Version_2_2);

storitve.AddSwaggerGen (c =>

            {

c.SwaggerDoc ("v1", nove informacije

                {

Različica = "v1",

Naslov = "Swagger Demo",

Opis = "Swagger Demo za ValuesController",

TermsOfService = "Brez",

Stik = nov stik () {Name = "Joydip Kanjilal",

E-pošta = "[email protected]",

Url = "www.google.com"

                }

                });

            });

        }

javna void Configure (aplikacija IApplicationBuilder,

IHostingEnvironment env)

        {

if (env.IsDevelopment ())

            {

app.UseDeveloperExceptionPage ();

            }

app.UseMvc ();

app.UseSwagger ();

app.UseSwaggerUI (c =>

            {

c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

            });

        }

    }

}

To je vse, kar morate storiti, da začnete uporabljati Swagger.

Prebrskajte uporabniški vmesnik Swagger aplikacije ASP.Net Core

Zdaj smo pripravljeni za zagon aplikacije in brskanje po končni točki Swagger. Prikaže se uporabniški vmesnik Swagger, kot je prikazano na sliki 1 spodaj. Upoštevajte, kako Swagger uporablja različne barve za glagole HTTP GET, PUT, POST in DELETE. Vsako končno točko, prikazano na sliki 1, lahko izvedete neposredno iz uporabniškega vmesnika Swagger.

Ustvarite komentarje XML v načinih delovanja krmilnika

Zaenkrat dobro. V prej ustvarjenem dokumentu Swagger ni bilo nobenih komentarjev XML. Če želite v dokumentu Swagger prikazati komentarje XML, potem te komentarje preprosto zapišete v načine delovanja krmilnika.

Zapišimo zdaj komentarje za vsak način dejanja v nadzorniku vrednosti. Tu je posodobljena različica programa ValuesController s komentarji XML za vsak način dejanja.

  [Pot ("api / [krmilnik]")]

[ApiController]

javni razred ValuesController: ControllerBase

    {

        ///

/// Pridobite akcijsko metodo brez argumenta

        ///

        ///

[HttpGet]

javni ActionResult Pridobite ()

        {

vrni nov niz [] {"value1", "value2"};

        }

        ///

/// Pridobite akcijsko metodo, ki sprejme celo število kot argument

        ///

        ///

        ///

[HttpGet ("{id}")]

public ActionResult Get (int id)

        {

vrni "vrednost";

        }

        ///

/// Metoda objave dejanja za dodajanje podatkov

        ///

        ///

[HttpPost]

public void Post (vrednost niza [[FromBody]])

        {

        }

        ///

/// Vnesite akcijsko metodo za spreminjanje podatkov

        ///

        ///

        ///

[HttpPut ("{id}")]

public void Put (int id, vrednost niza [FromBody])

        {

        }

        ///

/// Izbriši način dejanja

        ///

        ///

[HttpDelete ("{id}")]

public void Delete (int id)

        {

        }

    }

Vklopite komentarje XML v Swaggerju

Upoštevajte, da Swagger privzeto ne prikazuje komentarjev XML. To funkcijo morate vklopiti. Če želite to narediti, z desno miškino tipko kliknite Project, izberite Properties in nato pojdite na jeziček Build. Na zavihku Build izberite možnost »XML dokumentacijska datoteka«, da določite mesto, kjer bo ustvarjena dokumentacijska datoteka XML.

Določite tudi, da morajo biti pri ustvarjanju dokumenta Swagger vključeni komentarji XML, tako da v metodo ConfigureServices vpišete naslednjo kodo.

c.IncludeXmlComments (@ "D: \ Projects \ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");

In to je vse, kar morate storiti, da v Swaggerju vklopite komentarje XML.

Začetni URL aplikacije nastavite na Swagger UI

URL za zagon aplikacije lahko spremenite, da določite, da se bo uporabniški vmesnik Swagger naložil ob zagonu aplikacije. Če želite to narediti, z desno miškino tipko kliknite Project in izberite Properties. Nato pojdite na zavihek za odpravljanje napak. Nazadnje vrednost Launch Browser navedite kot razmetavanje, kot je prikazano na sliki 2.

Ko znova zaženete aplikacijo in se pomaknete do URL-ja Swagger, bi morali videti uporabniški vmesnik Swagger, kot je prikazano na sliki 3 spodaj. Tokrat upoštevajte komentarje XML v vsaki od metod API.

Swashbuckle je odlično orodje za ustvarjanje dokumentov Swagger za vaš API. Najpomembneje pa je, da je Swashbuckle enostavno konfigurirati in uporabljati. Swagger lahko storite veliko več, kot smo videli tukaj. Uporabniški vmesnik Swagger lahko prilagodite s pomočjo kaskadnih tabel slogov, vrednosti naštevanja prikažete kot vrednosti nizov in ustvarite različne dokumente Swagger za različne različice vašega API-ja, če jih naštejemo le nekaj.

$config[zx-auto] not found$config[zx-overlay] not found