Documentação da API web ASP.NET Core com Swagger / OpenAPI

Por Rico Suter

Swagger (OpenAPI) é uma especificação agnóstica de linguagem para descrever REST APIs. Ele permite que computadores e humanos entendam os recursos de uma REST API sem acesso direto ao código-fonte. Os seus principais objetivos são:

• Minimize a quantidade de trabalho necessária para conectar serviços dissociados.
• Reduza o tempo necessário para documentar com precisão um serviço.

As duas principais implementações OpenAPI para .NET são Swashbuckle e NSwag, consulte:

• Introdução ao Swashbuckle
• Introdução ao NSwag

OpenAPI vs. Swagger

O projeto Swagger foi doado à OpenAPI Initiative em 2015 e desde então tem sido referido como 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 comerciais e de código aberto da SmartBear que funcionam com a especificação OpenAPI. 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 pela SmartBear.

Em resumo:

• OpenAPI é uma especificaçã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 sua API. O documento é baseado no XML e anotações de atributos dentro dos controladores e modelos. É a parte central do fluxo OpenAPI e é usado para impulsionar ferramentas como SwaggerUI. Por padrão, ele é chamado openapi.json. Aqui está um exemplo de uma especificação OpenAPI, reduzida para brevidade:

{
  "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 fornece informações sobre o serviço, usando a especificação OpenAPI gerada. Tanto o Swashbuckle como o NSwag incluem uma versão incorporada do Swagger UI, permitindo que seja hospedada na sua aplicação ASP.NET Core através de uma chamada de registro de middleware. A interface do usuário da Web tem esta aparência:

Cada método de ação pública em seus controladores pode ser testado a partir da interface do usuário. Selecione um nome de método para expandir a seção. Adicione os parâmetros necessários e selecione Experimentar!.

Observação

A versão Swagger UI usada para as capturas de tela é a versão 2. Para obter um exemplo da versão 3, consulte Exemplo de Petstore.

Protegendo endpoints do Swagger UI

Chame MapSwagger().RequireAuthorization para proteger os endpoints do Swagger UI. O exemplo a seguir garante a segurança dos pontos de extremidade 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 /weatherforecast endpoint não requer autorização, mas os endpoints do Swagger requerem.

O Curl a seguir passa um token JWT para testar o ponto de extremidade da interface do Swagger.

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

Para obter mais informações sobre como testar com tokens JWT, consulte Gerar tokens com dotnet user-jwts.

Gere um arquivo de documentação XML em tempo de compilação.

Consulte GenerateDocumentationFile para obter mais informações.

Próximos passos

• Introdução ao Swashbuckle
• Introdução ao NSwag