Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Por Rico Suter
En este artículo se describe el uso de herramientas de Swagger ( proporcionados por los paquetes Swashbuckle.AspNetCore y NSwag ) para generar documentación de OpenAPI y páginas de ayuda interactivas para las API web de ASP.NET Core.
En .NET 9 y versiones posteriores, ASP.NET Core incluye compatibilidad integrada con OpenAPI que reemplaza Swashbuckle como valor predeterminado. Swashbuckle ya no se incluye en las plantillas de proyecto, pero sigue estando disponible como paquete de comunidad que puede agregar manualmente.
- Para comprender las características integradas de OpenAPI, consulte Introducción a la compatibilidad con OpenAPI en ASP.NET aplicaciones de API principales.
- Para agregar la interfaz de usuario de Swagger para la exploración interactiva o las pruebas ad hoc locales junto con la compatibilidad integrada con OpenAPI, consulte Uso de los documentos openAPI generados.
Las instrucciones siguientes se aplican a los proyectos que usan Swashbuckle o NSwag con ASP.NET Core 8.0 y versiones anteriores.
Swagger (OpenAPI) es una especificación independiente del lenguaje que sirve para describir API REST. Permite a los equipos y a los usuarios comprender las capacidades de una API REST sin acceso directo al código fuente. Sus principales objetivos son los siguientes:
- Minimizar la cantidad de trabajo necesaria para conectar los servicios desacoplados.
- Reducir la cantidad de tiempo necesario para documentar un servicio con precisión.
Las dos implementaciones principales de OpenAPI para .NET son Swashbuckle y NSwag, consulte:
OpenApi en comparación con Swagger
El proyecto de Swagger se donó a la iniciativa OpenAPI en 2015 y desde entonces se conoce como OpenAPI. Ambos nombres se usan indistintamente. Sin embargo, "OpenAPI" hace referencia a la especificación. "Swagger" hace referencia a la familia de productos comerciales y de código abierto de Smartbear que funcionan con la especificación OpenAPI. Los siguientes productos de código abierto, como OpenAPIGenerator, también se encuentran bajo el nombre de la familia de Swagger, a pesar de no ser publicados por Smartbear.
En resumen:
- OpenAPI es una especificación.
- Swagger es una herramienta que usa la especificación OpenAPI. Por ejemplo, OpenAPIGenerator y SwaggerUI.
Especificación de OpenAPI (openapi.json)
La especificación OpenAPI es un documento que describe las capacidades de la API. El documento se basa en XML y anotaciones de atributos dentro de los controladores y modelos. Es la parte principal del flujo OpenAPI y se usa para impulsar herramientas como SwaggerUI. De forma predeterminada, se denomina openapi.json. Este es un ejemplo de especificación de OpenAPI (se ha reducido por motivos de brevedad):
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Interfaz de usuario de Swagger
La interfaz de usuario de OpenAPI es una interfaz de usuario basada en Internet que proporciona información sobre el servicio por medio de la especificación de Swagger generada. Swashbuckle y NSwag incluyen una versión insertada de la interfaz de usuario de Swagger, de modo que se puede hospedar en una aplicación ASP.NET Core realizando una llamada de registro de middleware. La interfaz de usuario web tiene este aspecto:
Todos los métodos de acción públicos aplicados a los controladores se pueden probar desde la interfaz de usuario. Seleccione un nombre de método para expandir la sección. Agregue todos los parámetros necesarios y seleccione Try it out! (¡Pruébelo!).
Nota
La versión de interfaz de usuario de Swagger usada para las capturas de pantalla es la versión 2. Para obtener un ejemplo de la versión 3, vea el ejemplo de Petstore.
Proteger puntos de conexión de interfaz de usuario de Swagger
Llamar MapSwagger().RequireAuthorizationpara proteger los puntos de conexión de la interfaz de usuario de Swagger. En el ejemplo siguiente se protegen los puntos de conexión de Swagger:
using System.Security.Claims;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapSwagger().RequireAuthorization();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
.RequireAuthorization();
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();
app.Run();
internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
En el código anterior, el punto de conexión /weatherforecast no necesita autorización, pero sí los puntos de conexión de Swagger.
El siguiente comando Curl pasa un token JWT para probar el endpoint de Swagger UI.
curl -i -H "Authorization: Bearer {TOKEN}" https://localhost:{PORT}/swagger/v1/swagger.json
donde el {TOKEN} marcador de posición es el token de portador JWT y el {PORT} marcador de posición es el número de puerto.
Para obtener más información sobre las pruebas con tokens JWT, consulte Generación de tokens con dotnet user-jwts.
Generación de un archivo de documentación XML en tiempo de compilación
Consulte GenerateDocumentationFile para obtener más información.
Pasos siguientes
- Get started with Swashbuckle (Introducción a Swashbuckle)
- Get started with NSwag (Introducción a NSwag)
Por Rico Suter
Swagger (OpenAPI) es una especificación independiente del lenguaje que sirve para describir API REST. Permite a los equipos y a los usuarios comprender las capacidades de una API REST sin acceso directo al código fuente. Sus principales objetivos son los siguientes:
- Minimizar la cantidad de trabajo necesaria para conectar los servicios desacoplados.
- Reducir la cantidad de tiempo necesario para documentar un servicio con precisión.
Las dos implementaciones principales de OpenAPI para .NET son Swashbuckle y NSwag, consulte:
OpenApi en comparación con Swagger
El proyecto de Swagger se donó a la iniciativa OpenAPI en 2015 y desde entonces se conoce como OpenAPI. Ambos nombres se usan indistintamente. Sin embargo, "OpenAPI" hace referencia a la especificación. "Swagger" hace referencia a la familia de productos comerciales y de código abierto de Smartbear que funcionan con la especificación OpenAPI. Los siguientes productos de código abierto, como OpenAPIGenerator, también se encuentran bajo el nombre de la familia de Swagger, a pesar de no ser publicados por Smartbear.
En resumen:
- OpenAPI es una especificación.
- Swagger es una herramienta que usa la especificación OpenAPI. Por ejemplo, OpenAPIGenerator y SwaggerUI.
Especificación de OpenAPI (openapi.json)
La especificación OpenAPI es un documento que describe las capacidades de la API. El documento se basa en XML y anotaciones de atributos dentro de los controladores y modelos. Es la parte principal del flujo OpenAPI y se usa para impulsar herramientas como SwaggerUI. De forma predeterminada, se denomina openapi.json. Este es un ejemplo de especificación de OpenAPI (se ha reducido por motivos de brevedad):
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Interfaz de usuario de Swagger
La interfaz de usuario de OpenAPI es una interfaz de usuario basada en Internet que proporciona información sobre el servicio por medio de la especificación de Swagger generada. Swashbuckle y NSwag incluyen una versión insertada de la interfaz de usuario de Swagger, de modo que se puede hospedar en una aplicación ASP.NET Core realizando una llamada de registro de middleware. La interfaz de usuario web tiene este aspecto:
Todos los métodos de acción públicos aplicados a los controladores se pueden probar desde la interfaz de usuario. Seleccione un nombre de método para expandir la sección. Agregue todos los parámetros necesarios y seleccione Try it out! (¡Pruébelo!).
Nota
La versión de interfaz de usuario de Swagger usada para las capturas de pantalla es la versión 2. Para obtener un ejemplo de la versión 3, vea el ejemplo de Petstore.
Pasos siguientes
- Get started with Swashbuckle (Introducción a Swashbuckle)
- Get started with NSwag (Introducción a NSwag)
Colaborar con nosotros en GitHub
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.
