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 Visual Studio 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 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.

"launchBrowser": true,
"launchUrl": "scalar",

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 Spectral para el análisis de documentos OpenAPI en tiempo de compilación, instale primero el paquete para habilitar la generación de documentos 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)

Compatibilidad para la inserción de IOpenApiDocumentProvider

Puede insertar IOpenApiDocumentProvider en los servicios a través de la inserción de dependencias para acceder a documentos openAPI mediante programación, incluso fuera de los contextos de solicitud HTTP.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

Registre el servicio en su contenedor de DI:

builder.Services.AddScoped<DocumentService>();

Esto permite escenarios como generar SDK de cliente, validar contratos de API en procesos en segundo plano o exportar documentos a sistemas externos.

La compatibilidad con la inserción IOpenApiDocumentProvider se introdujo en ASP.NET Core en .NET 10. Para obtener más información, vea dotnet/aspnetcore #61463.