Uso de documentos de OpenAPI

Uso de la interfaz de usuario de Swagger para pruebas ad hoc locales

De forma predeterminada, el paquete de Microsoft.AspNetCore.OpenApi no incluye compatibilidad integrada para visualizar o interactuar con el documento de OpenAPI. Entre las herramientas populares para visualizar o interactuar con el documento de OpenAPI se incluyen Interfaz de usuario de Swagger y ReDoc. La interfaz de usuario de Swagger y ReDoc se pueden integrar de varias maneras en una aplicación. Los editores como Visual Studio y VS Code ofrecen extensiones y experiencias integradas para realizar pruebas en un documento de OpenAPI.

El paquete Swashbuckle.AspNetCore.SwaggerUi proporciona una agrupación de los recursos web de la interfaz de usuario de Swagger para su uso en aplicaciones. Este paquete se puede usar para representar una interfaz de usuario para el documento generado. Para configurar estos:

• Instale el paquete Swashbuckle.AspNetCore.SwaggerUi.
• Habilite el middleware swagger-ui con una referencia a la ruta de OpenAPI registrada anteriormente.
• Para limitar la divulgación de información y la vulnerabilidad de seguridad, habilite solo la interfaz de usuario de Swagger en entornos de desarrollo.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

Uso de Scalar para la documentación de la API interactiva

Scalar es una interfaz de usuario de documentos interactiva de código abierto para OpenAPI. Scalar se puede integrar con el punto de conexión de OpenAPI proporcionado por ASP.NET Core. Para configurar Scalar, instale el paquete Scalar.AspNetCore.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Lint generó documentos de OpenAPI con Spectral

Spectral es un linter de documentos de OpenAPI de código abierto. Spectral se puede incorporar en una compilación de la aplicación para comprobar la calidad de los documentos de OpenAPI generados. Instale Spectral según las instrucciones de instalación del paquete.

Para aprovechar las ventajas de Spectral, instale el paquete Microsoft.Extensions.ApiDescription.Server para habilitar la generación de documentos de OpenAPI en tiempo de compilación.

Habilita la generación de documentos en tiempo de compilación estableciendo las siguientes propiedades en el archivo .csproj de la aplicación:

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

Ejecute dotnet build para generar el documento.

dotnet build

Cree un archivo .spectral.yml con el siguiente contenido.

extends: ["spectral:oas"]

Ejecute spectral lint en el archivo generado.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)