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 esto:

• Instale el paquete Swashbuckle.AspNetCore.SwaggerUi.
• Habilite el middleware swagger-ui con una referencia a la ruta de OpenAPI registrada anteriormente.

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();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

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

}

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

app.Run();

Como procedimiento recomendado de seguridad para limitar la divulgación de información, las interfaces de usuario de OpenAPI (Interfaz de usuario de Swagger, ReDoc, Scalar) solo deben habilitarse en entornos de desarrollo. Por ejemplo, consulte Configuración de OAuth 2.0 de Swagger.

Inicie la aplicación y vaya a https://localhost:<port>/swagger para ver la interfaz de usuario de Swagger.

Para iniciar automáticamente la aplicación en el URL de Swagger UI mediante el perfil de https de Properties/launchSettings.json:

• Confirme que launchBrowser está habilitado (true).
• Establecer launchUrl en swagger.

"launchBrowser": true,
"launchUrl": "swagger",

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();

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

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

app.Run();

Inicie la aplicación y vaya a https://localhost:<port>/scalar/v1 para ver la interfaz de usuario escalar.

Para iniciar automáticamente la aplicación en la URL de la interfaz de usuario de Scalar utilizando el perfil de https de Properties/launchSettings.json:

• Confirme que launchBrowser está habilitado (true).
• Establecer launchUrl en scalar/v1.

"launchBrowser": true,
"launchUrl": "scalar/v1",

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)