Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Por Rico Suter
Este artigo aborda o uso de ferramentas do Swagger , fornecidas pelos pacotes Swashbuckle.AspNetCore e NSwag , para gerar a documentação do OpenAPI e páginas de ajuda interativas para apIs Web do ASP.NET Core.
No .NET 9 e posterior, o ASP.NET Core inclui suporte interno ao OpenAPI que substitui o Swashbuckle como o padrão. O Swashbuckle não está mais incluído nos modelos de projeto, mas ele permanece disponível como um pacote de comunidade que você pode adicionar manualmente.
- Para entender os recursos internos do OpenAPI, consulte Visão geral do suporte ao OpenAPI em aplicativos de API do ASP.NET Core.
- Para adicionar a interface do usuário do Swagger para exploração interativa ou teste ad hoc local juntamente com o suporte interno do OpenAPI, consulte Usar os documentos OpenAPI gerados.
As instruções a seguir se aplicam a projetos usando Swashbuckle ou NSwag com ASP.NET Core 8.0 e anteriores.
Swagger (OpenAPI) é uma especificação independente de linguagem para descrever APIs REST. Ele permite que computadores e humanos entendam os recursos de uma API REST sem acesso direto ao código-fonte. Seus principais objetivos são:
- Minimize a quantidade de trabalho necessária para conectar serviços separados.
- Reduza o tempo necessário para documentar um serviço com precisão.
As duas principais implementações do OpenAPI para .NET são Swashbuckle e NSwag, confira:
OpenAPI vs. Swagger
O projeto Swagger foi doado para a OpenAPI Initiative em 2015 e, desde então, foi chamado de OpenAPI. Ambos os nomes são usados de forma intercambiável. No entanto, "OpenAPI" refere-se à especificação. "Swagger" refere-se à família de produtos de código aberto e comerciais do SmartBear que funcionam com a Especificação do OpenAPI. Os produtos de código aberto subsequentes, como OpenAPIGenerator, também se enquadram no nome da família Swagger, apesar de não terem sido lançados pelo SmartBear.
Resumindo:
- O OpenAPI é uma especificação.
- O Swagger é uma ferramenta que usa a especificação OpenAPI. Por exemplo, OpenAPIGenerator e SwaggerUI.
Especificação OpenAPI (openapi.json)
A especificação OpenAPI é um documento que descreve os recursos da API. O documento baseia-se no XML e nas anotações de atributos dentro dos controladores e modelos. Ele é a parte principal do fluxo OpenAPI e é usado para impulsionar ferramentas como SwaggerUI. Por padrão, ele é chamado de openapi.json. Aqui está um exemplo de uma especificação do OpenAPI, resumida:
{
"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
}
}
}
}
Interface do usuário do Swagger
A Interface do usuário do Swagger oferece uma interface do usuário baseada na Web que conta com informações sobre o serviço, usando a especificação do OpenAPI gerada. Swashbuckle e NSwag incluem uma versão incorporada do Swagger UI, permitindo sua hospedagem em seu aplicativo ASP.NET Core usando uma chamada de registro de middleware. A interface do usuário da Web tem esta aparência:
Todo método de ação pública nos controladores pode ser testado da interface do usuário. Selecione um nome de método para expandir a seção. Adicione os parâmetros necessários e selecione Experimente!.
Observação
A versão da interface do usuário do Swagger usada para as capturas de tela é a versão 2. Para obter um exemplo da versão 3, confira Exemplo Petstore.
Protegendo os endpoints do Swagger UI
Chame MapSwagger().RequireAuthorization para proteger os endpoints da interface Swagger. O exemplo a seguir protege os endpoints do 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);
}
No código anterior, o endpoint /weatherforecast não requer autorização, mas os endpoints do Swagger necessitam.
O Curl a seguir passa um token JWT para testar o endpoint do Swagger UI.
curl -i -H "Authorization: Bearer {TOKEN}" https://localhost:{PORT}/swagger/v1/swagger.json
em que o {TOKEN} espaço reservado é o token de portador JWT e o {PORT} espaço reservado é o número da porta.
Para obter mais informações sobre como testar com tokens JWT, confira Gerar tokens com dotnet user-jwts.
Gerar um arquivo de documentação XML em tempo de compilação
Confira GenerateDocumentationFile para obter mais informações.
Próximas etapas
Por Rico Suter
O Swagger (OpenAPI) é uma especificação independente de linguagem para descrever APIs REST. Ele permite que computadores e humanos entendam os recursos de uma API REST sem acesso direto ao código-fonte. Seus principais objetivos são:
- Minimize a quantidade de trabalho necessária para conectar serviços separados.
- Reduza o tempo necessário para documentar um serviço com precisão.
As duas principais implementações do OpenAPI para .NET são Swashbuckle e NSwag, confira:
OpenAPI vs. Swagger
O projeto Swagger foi doado para a OpenAPI Initiative em 2015 e, desde então, foi chamado de OpenAPI. Ambos os nomes são usados de forma intercambiável. No entanto, "OpenAPI" refere-se à especificação. "Swagger" refere-se à família de produtos de código aberto e comerciais do SmartBear que funcionam com a Especificação do OpenAPI. Os produtos de código aberto subsequentes, como OpenAPIGenerator, também se enquadram no nome da família Swagger, apesar de não terem sido lançados pelo SmartBear.
Resumindo:
- O OpenAPI é uma especificação.
- O Swagger é uma ferramenta que usa a especificação OpenAPI. Por exemplo, OpenAPIGenerator e SwaggerUI.
Especificação OpenAPI (openapi.json)
A especificação OpenAPI é um documento que descreve os recursos da API. O documento baseia-se no XML e nas anotações de atributos dentro dos controladores e modelos. Ele é a parte principal do fluxo OpenAPI e é usado para impulsionar ferramentas como SwaggerUI. Por padrão, ele é chamado de openapi.json. Aqui está um exemplo de uma especificação do OpenAPI, resumida:
{
"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
}
}
}
}
Interface do usuário do Swagger
A Interface do usuário do Swagger oferece uma interface do usuário baseada na Web que conta com informações sobre o serviço, usando a especificação do OpenAPI gerada. Swashbuckle e NSwag incluem uma versão incorporada do Swagger UI, permitindo sua hospedagem em seu aplicativo ASP.NET Core usando uma chamada de registro de middleware. A interface do usuário da Web tem esta aparência:
Todo método de ação pública nos controladores pode ser testado da interface do usuário. Selecione um nome de método para expandir a seção. Adicione os parâmetros necessários e selecione Experimente!.
Observação
A versão da interface do usuário do Swagger usada para as capturas de tela é a versão 2. Para obter um exemplo da versão 3, confira Exemplo Petstore.
Próximas etapas
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
