Como interpretar um Swagger
O que é um Swagger?
Se alguma vez você já trabalhou com APIs existe uma chance grande de já ter ouvido falar de Swagger. Swagger é uma das ferramentas mais utilizadas para o desenvolvimento de OpenAPI Specification(OAS).
Swagger permite que você descreva a estrutura de APIs de uma forma facilitada onde é possível a interpretação tanto por humanos quanto por máquinas. Swagger consegue ler a estrutura da sua API e gerar automaticamente uma documentação ou ler a documentação e gerar uma API. Esta documentação descreve algumas informações:
- Quais são todas as operações que sua API suporta.
- Quais são os parâmetros de sua API e o que ela retorna.
- Se sua API precisa de alguma autorização.
Você pode escrever uma especificação Swagger para sua API manualmente, ou ter ela gerada automaticamente por anotações no seu código fonte.
Estrutura Básica
O Swagger pode ser escrito em JSON ou YAML, abaixo um exemplo:
Metadata
Toda especificação Swagger inicia com a versão do Swagger, 2.0 é a ultima versão.
Abaixo temos as informações de Título, Descrição e Versão da API.
Base URL
A URL Base é formada por host, basePath e schemes.
Neste swagger de exemplo quando falamos do path /user na verdade a URL completa seria https://api.example.com/v1/users.
Consumes, Produces
A sessão Consumes e Produces descreve os tipos suportados pela API.
Paths
A sessão Paths define um endpoint individual na sua API e qual o método HTTP suportado por este endpoint. Por exemplo GET /users pode ser descrito como:
Parameters
As operações podem ter parâmetros que serão informados via URL Path (/users/{userId}), Query String (/users?userId=123), Headers (X-customHeader: Value) e Request Body. Você pode definir os tipos dos parâmetros , formato, obrigatoriedade e outros detalhes:
Neste exemplo possuímos um endpoint /users que recebe a passagem do parâmetro no path, o nome do parâmetro é userId, ele é obrigatório e do tipo inteiro.
Responses
Para cada operação você pode definir os status code possíveis, como 200 OK ou 404 Not Found, pode definir também o schema do Response body. Schemas podem ser definidos inline ou referenciado externamente via $ref. Você pode prover também exemplos de respostas.
No exemplo acima vemos a descrição das respostas esperadas 200, 400 e 404 e a descrição de cada uma das respostas. Vamos escrever a representação em Json da resposta 200:
Ou seja, a propriedade id é um inteiro e a propriedade name é uma string. E como ficaria o Json da resposta 400?
Schema
Vamos utilizar um exemplo prático de como fazer referência para um schema. Abaixo temos o exemplo de uma saída:
Esta saída pode ser representada da forma abaixo:
Uma vez que possímos a definição de quais propriedades devem haver para um User podemos fazer referência a ele no request body e no response do Swagger conforme abaixo:
Autentication
As palavras securityDefinitions e security são utilizadas para definir a segurança da API e os métodos de autenticação.
Referência
