Documentação da API Web ASP.NET Core com o Swagger/OpenAPI
Por Christoph Nienaber e Rico Suter
O Swagger (OpenAPI) é uma especificação independente 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. Seus principais objetivos são:
- Minimize a quantidade de trabalho necessária para conectar serviços separados.
- Reduza o tempo necessário para documentar com precisão um serviço.
As duas principais implementações de OpenAPI para .NET são Swashbuckle e NSwag, consulte:
OpenAPI vs. Swagger
O projeto Swagger foi doado para a Iniciativa OpenAPI 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 software livre e comerciais do SmartBear que funcionam com a Especificação openAPI. Os produtos de software livre subsequentes, como OpenAPIGenerator, também se enquadram no nome da família Swagger, apesar de não terem sido lançados pelo SmartBear.
Resumindo:
- OpenAPI é uma especificação.
- O Swagger é uma ferramenta que usa a especificação OpenAPI. Por exemplo, OpenAPIGenerator e SwaggerUI.
Especificação de OpenAPI (openapi.json)
A especificação OpenAPI é um documento que descreve os recursos de sua API. O documento é baseado no XML e nas anotações de atributo dentro dos controladores e modelos. É a parte principal do fluxo OpenAPI e é usada para impulsionar ferramentas como SwaggerUI. Por padrão, ele é chamado openapi.jsonde . Aqui está um exemplo de uma especificação de OpenAPI, reduzida para fins de 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
}
}
}
}
Swagger UI
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 de 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 Experimentar!.
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.