ASP.NET:use Swagger para generar documentación API

La forma más sencilla de agregar documentación API es usar Swagger. Puede configurarlo para generar una página de documentación de API e incluso enviar solicitudes a sus puntos finales. Así es como se ve:

En este artículo, mostraré cómo instalar y configurar Swagger con las siguientes funciones (que se muestran en la imagen de arriba):

• Genera una página de documentación de la API.
• Muestra comentarios XML para el controlador y los objetos utilizados en la solicitud (el esquema).
• Muestra campos obligatorios.

1:instale el paquete nuget Swagger ASP.NET

• Buscar el paquete Swashbuckle.AspNetCore
• Instálelo

Esto instala los tres paquetes que necesita:

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

2:agregue el servicio Swagger y el middleware en el inicio

Agregue Swagger en ConfigureServices(…) y Configure(…). Vea las líneas resaltadas en el código a continuación.

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:configurarlo para iniciar la página de documentación de la API de Swagger

En /Properties/launchSettings.json, establezca launchUrl en "swagger".

{
  "$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:genera automáticamente documentación XML a partir de comentarios XML

Para que Swagger muestre comentarios XML, debe hacer que su proyecto genere un archivo de documentación XML.

En las propiedades de compilación del proyecto, marque archivo de documentación XML.

5 – Agregar comentarios XML y el atributo [Requerido]

Aquí está la clase StockMarketController y Stock. Puse comentarios XML – ///

en propiedades y métodos, y usé el atributo [Required] en la clase Stock. Swagger mostrará estos comentarios XML y mostrará qué campos son obligatorios.

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 – Inicie su API web y envíe una solicitud a través de [Pruébelo] de Swagger

• Inicie su proyecto (Iniciar sin depurar – Ctrl+F5). Esto abrirá la página de documentos de Swagger en el navegador.
• Haga clic en Pruébelo

• Complete el JSON del cuerpo de la solicitud y haga clic en Ejecutar.

• Mira la respuesta.