Hur man använder Swagger i ASP.Net Core

Du vill ofta skapa dokumentation för ditt API. För att skapa denna dokumentation kan du dra nytta av Swagger - ett verktyg som kan användas för att enkelt tillhandahålla en UI-representation av ditt API. När du väl har skapat Swagger-dokumentation för ditt API kan du se signaturen för dina API-metoder och till och med testa dina API-metoder också.

Swashbuckle är ett open source-projekt för att generera Swagger-dokument. Den här artikeln presenterar en diskussion om hur vi kan dra nytta av Swashbuckle för att generera interaktiv dokumentation för vårt RESTful API.

Skapa ett ASP.Net Core-projekt

Låt oss först skapa ett ASP.Net Core-projekt i Visual Studio. Förutsatt att Visual Studio 2017 eller Visual Studio 2019 är installerat i ditt system, följ stegen nedan för att skapa ett nytt ASP.Net Core-projekt i Visual Studio.

  1. Starta Visual Studio IDE.
  2. Klicka på "Skapa nytt projekt."
  3. I fönstret "Skapa nytt projekt" väljer du "ASP.Net Core Web Application" från listan över mallar som visas.
  4. Klicka på Nästa. 
  5. I fönstret ”Konfigurera ditt nya projekt” som visas nedan anger du namn och plats för det nya projektet.
  6. Klicka på Skapa. 
  7. I fönstret “Skapa ny ASP.Net Core-webbapplikation” väljer du .Net Core som körtid och ASP.Net Core 2.2 (eller senare) från rullgardinslistan högst upp.
  8. Välj “API” som projektmall för att skapa ett nytt ASP.Net Core Web API-projekt. 
  9. Se till att kryssrutorna "Aktivera Docker-support" och "Konfigurera för HTTPS" är avmarkerade eftersom vi inte använder dessa funktioner här.
  10. Se till att autentisering är inställd som "Ingen autentisering" eftersom vi inte heller använder autentisering.
  11. Klicka på Skapa.

Genom att följa dessa steg skapas ett nytt ASP.Net Core-projekt i Visual Studio. Vi använder detta projekt i de efterföljande avsnitten i den här artikeln för att undersöka hur vi kan generera Swagger-dokumentation för ValuesController.

Installera Swagger middleware i ASP.Net Core

Om du har skapat ett ASP.Net Core-projekt med framgång är nästa sak du bör göra att lägga till nödvändiga NuGet-paket till ditt projekt. För att göra detta, välj projektet i Solution Explorer-fönstret, högerklicka och välj “Hantera NuGet-paket ....” I fönstret NuGet Package Manager, sök efter paketet Swashbuckle.AspNetCore och installera det. Alternativt kan du installera paketet via NuGet Package Manager-konsolen enligt nedan.

PM> Installera-paketet Swashbuckle.AspNetCore

Paketet Swashbuckle.AspNetCore innehåller nödvändiga verktyg för att generera API-dokument för ASP.Net Core.

Konfigurera Swagger middleware i ASP.Net Core

För att konfigurera Swagger, skriv följande kod i ConfigureServices-metoden. Observera hur AddSwaggerGen-tilläggsmetoden används för att specificera metadata för API-dokumentet.

services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", ny info

                {

                    Version = "v1",

                    Titel = "Swagger Demo",

                    Beskrivning = "Swagger Demo for ValuesController",

                    TermsOfService = "Ingen",

                    Kontakt = ny kontakt () {Namn = "Joydip Kanjilal",

                    E-post = "[email protected]",

                    Url = "www.google.com"}

                });

            });

Du bör också aktivera Swagger UI i konfigurationsmetoden som visas nedan.

app.UseSwagger ();

app.UseSwaggerUI (c =>

{

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

});

Här är den fullständiga koden för startklassen som referens.

med hjälp av Microsoft.AspNetCore.Builder;

använder Microsoft.AspNetCore.Hosting;

med hjälp av Microsoft.AspNetCore.Mvc;

med hjälp av Microsoft.Extensions.Configuration;

använder Microsoft.Extensions.DependencyInjection;

med hjälp av Swashbuckle.AspNetCore.Swagger;

namnområde SwaggerDemo

{

    allmän klass Startup

    {

        public Startup (IConfiguration configuration)

        {

            Configuration = konfiguration;

        }

        offentlig IConfiguration Configuration {get; }

        public void ConfigureServices (IServiceCollection services)

        {

            services.AddMvc (). SetCompatibilityVersion

            (CompatibilityVersion.Version_2_2);   

            services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", ny info

                {

                    Version = "v1",

                    Titel = "Swagger Demo",

                    Beskrivning = "Swagger Demo for ValuesController",

                    TermsOfService = "Ingen",

                    Kontakt = ny kontakt () {Namn = "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");

            });

        }

    }

}

Det här är allt du behöver göra för att komma igång med Swagger.

Bläddra i Swagger UI i din ASP.Net Core-app

Nu är vi redo att köra programmet och bläddra i Swagger-slutpunkten. Användargränssnittet för Swagger visas som i figur 1 nedan. Observera hur Swagger använder olika färger för HTTP-verben GET, PUT, POST och DELETE. Du kan köra var och en av slutpunkterna som visas i figur 1 direkt från Swagger UI.

Skapa XML-kommentarer i din handlings handlingsmetoder

Än så länge är allt bra. I Swagger-dokumentet som genererades tidigare fanns inga XML-kommentarer. Om du vill visa XML-kommentarer i Swagger-dokumentet skriver du helt enkelt dessa kommentarer i din handlings handlingsmetoder.

Låt oss nu skriva kommentarer för var och en av åtgärdsmetoderna i ValuesController. Här är den uppdaterade versionen av ValuesController med XML-kommentarer för var och en av åtgärdsmetoderna.

  [Rutt ("api / [controller]")]

    [ApiController]

    public class ValuesController: ControllerBase

    {

        ///

        /// Få åtgärdsmetod utan argument

        ///

        ///

        [HttpGet]

        offentlig ActionResult Skaffa sig()

        {

            returnera ny sträng [] {"value1", "value2"};

        }

        ///

        /// Få åtgärdsmetod som accepterar ett heltal som ett argument

        ///

        ///

        ///

        [HttpGet ("{id}")]

        offentlig ActionResult Get (int id)

        {

            returvärde";

        }

        ///

        /// Lägg upp åtgärdsmetod för att lägga till data

        ///

        ///

        [HttpPost]

        public void Post ([FromBody] strängvärde)

        {

        }

        ///

        /// Sätt handlingsmetod för att modifiera data

        ///

        ///

        ///

        [HttpPut ("{id}")]

        public void Put (int id, [FromBody] strängvärde)

        {

        }

        ///

        /// Ta bort åtgärdsmetod

        ///

        ///

        [HttpDelete ("{id}")]

        offentligt tomrum Ta bort (int-id)

        {

        }

    }

Aktivera XML-kommentarer i Swagger

Observera att Swagger inte visar XML-kommentarer som standard. Du måste aktivera den här funktionen. För att göra detta högerklickar du på Project, väljer Properties och navigerar sedan till fliken Build. På fliken Bygg markerar du alternativet "XML-dokumentationsfil" för att ange platsen där XML-dokumentationsfilen ska skapas.

Du bör också ange att XML-kommentarerna ska inkluderas när du skapar Swagger-dokumentet genom att skriva följande kod i ConfigureServices-metoden.

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

Och det är allt du behöver göra för att slå på XML-kommentarer i Swagger.

Ställ in startadressen för appen till Swagger UI

Du kan ändra din webbadress för applikationsstart för att ange att Swagger UI laddas när applikationen startas. För att göra detta högerklickar du på Projekt och väljer Egenskaper. Navigera sedan till fliken Felsökning. Slutligen, ange Starta webbläsarvärdet som swagger som visas i figur 2.

När du kör programmet igen och navigerar till Swagger URL, bör du se Swagger UI som visas i Figur 3 nedan. Observera XML-kommentarerna i var och en av API-metoderna den här gången.

Swashbuckle är ett utmärkt verktyg för att generera Swagger-dokument för ditt API. Viktigast är att Swashbuckle är lätt att konfigurera och använda. Det finns mycket mer du kan göra med Swagger än vi har sett här. Du kan anpassa Swagger UI med Cascading Style Sheets, visa enumvärden som strängvärden och skapa olika Swagger-dokument för olika versioner av ditt API, för att bara nämna några.