ASP.NET – Verwenden Sie Swagger, um API-Dokumentation zu generieren

 C Programming >> C-Programmierung >  >> Tags >> API
ASP.NET – Verwenden Sie Swagger, um API-Dokumentation zu generieren

Die einfachste Möglichkeit, API-Dokumentation hinzuzufügen, ist die Verwendung von Swagger. Sie können es so konfigurieren, dass es eine API-Dokumentationsseite generiert und sogar Anfragen an Ihre Endpunkte sendet. So sieht es aus:

In diesem Artikel zeige ich, wie Swagger mit den folgenden Funktionen installiert und konfiguriert wird (siehe Abbildung oben):

  • Erzeugt eine API-Dokumentationsseite.
  • Zeigt XML-Kommentare für den Controller und die Objekte an, die in der Anfrage verwendet werden (das Schema).
  • Zeigt erforderliche Felder an.

1 – Installieren Sie das Nuget-Paket Swagger ASP.NET

  • Suchen Sie nach dem Swashbuckle.AspNetCore-Paket
  • Installieren

Dadurch werden die drei benötigten Pakete installiert:

  • Swashbuckle.AspNetCore.Swagger
  • Swashbuckle.AspNetCore.SwaggerGen
  • Swashbuckle.AspNetCore.SwaggerUI

2 – Swagger-Dienst und Middleware in Startup hinzufügen

Fügen Sie Swagger in ConfigureServices(…) und Configure(…) hinzu. Siehe die hervorgehobenen Zeilen im Code unten.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System;
using System.IO;

namespace SimpleSwagger
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            //1 - Add Swagger service and include XML documentation
            services.AddSwaggerGen(c => 
            {
                var filePath = Path.Combine(AppContext.BaseDirectory, "SimpleSwagger.xml");
                c.IncludeXmlComments(filePath, includeControllerXmlComments: true);
            });

            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            //2 - Enable Swagger middleware
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
            });

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Code language: C# (cs)

3 – Konfigurieren Sie es, um die Swagger-API-Dokumentationsseite zu starten

Legen Sie in /Properties/launchSettings.json die launchUrl auf „swagger“ fest.

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:39257",
      "sslPort": 44379
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "SimpleSwagger": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Code language: JSON / JSON with Comments (json)

4 – XML-Dokumentation automatisch aus XML-Kommentaren generieren

Damit Swagger XML-Kommentare anzeigt, müssen Sie Ihr Projekt dazu bringen, eine XML-Dokumentationsdatei auszugeben.

Setzen Sie in den Build-Eigenschaften des Projekts ein Häkchen bei XML-Dokumentationsdatei.

5 – Fügen Sie XML-Kommentare und das Attribut [Erforderlich] hinzu

Hier ist die Klasse StockMarketController und Stock. Ich habe XML-Kommentare – ///

– zu Eigenschaften und Methoden hinzugefügt und das [Required]-Attribut in der Stock-Klasse verwendet. Swagger zeigt diese XML-Kommentare und zeigt, welche Felder erforderlich sind.

using Microsoft.AspNetCore.Mvc;
using System.ComponentModel.DataAnnotations;

namespace SimpleSwagger.Controllers
{
    [ApiController]
    [Route("stocks")]
    public class StockMarketController : ControllerBase
    {

        /// <summary>
        /// Updates information for a stock in the system
        /// </summary>
        /// <param name="stock"></param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult UpdateStock([FromBody]Stock stock)
        {
            //update the stock data in the system
            return Ok();
        }
    }

    /// <summary>
    /// Test
    /// </summary>
    public class Stock
    {
        /// <summary>
        /// Unique identifier of stock
        /// Ex: VTSAX (Vanguard Total Stock Market Index Fund)
        /// </summary>
        [Required]
        public string TickerSymbol { get; set; }
        /// <summary>
        /// The current price of the stock
        /// Ex: 82.20
        /// </summary>
        [Required]
        public decimal Price { get; set; }
    }
}

Code language: C# (cs)

6 – Starten Sie Ihre Web-API und senden Sie eine Anfrage über Swaggers [Try it out]

  • Starten Sie Ihr Projekt (Start ohne Debugging – Strg+F5). Dadurch wird die Swagger-Dokumentseite im Browser gestartet.
  • Klicken Sie auf Ausprobieren
  • Füllen Sie den Anforderungstext in JSON aus und klicken Sie dann auf Ausführen.
  • Sehen Sie sich die Antwort an.