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

Por Christoph Nienaber e Rico Suter

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:

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

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 em anotações de atributo e XML 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
      }
    }
  }
}

Swagger UI

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. O Swashbuckle e o NSwag incluem uma versão incorporada da interface do usuário do Swagger, para que ele possa ser hospedado 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.

Proteger pontos de extremidade da interface do usuário do Swagger

Chame MapSwagger().RequireAuthorization para proteger os pontos de extremidade da interface do usuário do Swagger. O exemplo a seguir protege os pontos de extremidade 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 ponto de extremidade /weatherforecast não precisa de autorização, mas os pontos de extremidade do Swagger precisam.

O Curl a seguir passa um token JWT para testar o ponto de extremidade da interface do usuário 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, confira Gerar tokens com dotnet user-jwts.

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

Confira GenerateDocumentationFile para obter mais informações.

Próximas etapas

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