Tutorial OpenAPI 3.0: 8 Dicas para Documentar a Especificação da API
Neste artigo, vamos destacar os pontos-chave do processo de atualização e os essenciais da documentação de APIs usando OAS 3. Alguns desses pontos podem ainda ser aplicáveis aos documentos anteriores OAS 2 (antigamente conhecidos como Swagger).
Anteriormente, você pode ter usado o Swagger 2.0 (também conhecido como OAS 2), mas agora é hora de atualizar para a Especificação OpenAPI (OAS) 3. Neste artigo, мы descreveremos os pontos-chave do processo de atualização e os elementos essenciais da documentação de APIs usando OAS 3.
Alguns desses pontos ainda podem ser aplicáveis aos documentos anteriores do OAS 2 (anteriormente conhecido como Swagger), mas vale a pena notar, pois pode ser que eu não os tenha enfatizado totalmente antes.
Os exemplos de código neste artigo são extraídos da especificação OAS 3 do bookmarks.dev-api, que está disponível no arquivo openapi.yaml no GitHub. Os resultados podem ser vistos em bookmarks.dev/api/docs/.
Aqui estão dez considerações principais:
1. Leia o Documento da Especificação
Leia o artigo "Um Guia sobre o que há de Novo no OpenAPI 3.0", que compartilha algumas das principais atualizações na versão mais recente do OAS e fornece insights detalhados sobre o que você precisa saber ao fazer a transição do OAS 2.0 para o OAS 3.0. Este artigo é baseado no webinar de 1 hora "OpenAPI 3.0, e o que isso significa para o futuro do Swagger."
2. Use um Serviço de Conversão na Web
Use o serviço de conversão OpenAPI/Swagger 2.0 para OpenAPI 3.0 para transformar suas especificações Swagger em OpenAPI 3.0.
Está disponível online em https://converter.swagger.io/, e você também pode usá-lo como uma imagem Docker:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. Valide Sua Especificação e Visualize com o Swagger Editor
O Swagger Editor permite que você edite especificações de API Swagger formatadas em YAML em seu navegador e visualize instantaneamente a documentação.
Você pode usá-lo online ou como uma versão publicada no npm ou uma imagem Docker. Para mais detalhes, consulte o README do projeto.
4. Apresente Sua Documentação com o Swagger UI
O Swagger UI é uma coleção de recursos HTML, JavaScript e CSS que geram dinamicamente uma bela documentação para APIs compatíveis com Swagger.
Você pode usá-lo diretamente, como eu, acessando a documentação do Swagger UI através de uma rota de API, por exemplo, bookmarks.dev/api/docs/. Aqui está um trecho de código do app.js:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Incluir o arquivo de especificação aberto (openapi.yaml) no seu monitor do nodemon (por exemplo, nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) pode ser útil, permitindo que você recarregue a UI sem reiniciar manualmente o servidor ExpressJS.
4.1. Use o swagger-jsdoc para Abordagem Code-First
Outro ponto digno de nota é que você pode usar o swagger-jsdoc para integrar o Swagger através de anotações JSDoc em seu código. O projeto swagger-jsdoc pressupõe que você queira documentar um código existente, ativo e funcional de forma que "dê vida" a ele, gerando uma especificação que pode ser alimentada em outras ferramentas Swagger, em vez do contrário.
Atualmente, eu gerencio a documentação em um único arquivo openapi.yaml, mas posso considerar usá-lo no futuro.
5. Agrupe Operações Usando Tags
Você pode atribuir uma lista de tags a cada operação da API, facilitando para o Swagger UI e o Swagger Editor exibir operações por tags. Para controlar a ordenação no Swagger UI, você precisa adicioná-las como tags globais no nível raiz. Você também pode adicionar descrições e links para documentos externos lá.
Aqui estão as tags que uso para a API:
yamlCopy code
tags:- name: rootdescription: Usado para marcar endpoints raiz- name: versiondescription: Acesse a versão do projeto e gitSha1- name: public-bookmarksdescription: Acesse marcadores públicos- name: personal-bookmarksdescription: Operações em marcadores pessoais- name: user-datadescription: Operações em dados do usuário- name: helperdescription: Endpoints/oper ações auxiliares
6. Especifique URLs Base da API com Servidores
No OpenAPI 3.0, você usa o array servers para especificar uma ou mais URLs base para a API. Os servidores substituem as palavras-chave host, basePath e schemes usadas no OpenAPI 2.0. Cada servidor tem uma URL e uma descrição opcional em formato Markdown.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: Servidor local para desenvolvimento- url: https://www.bookmarks.dev/apidescription: Servidor principal (produção)
7. Defina e Reutilize Recursos com Componentes
Frequentemente, várias operações de API compartilham parâmetros comuns ou retornam a mesma estrutura de resposta. Para evitar duplicação de código, você pode colocar definições comuns na seção global de componentes e referenciá-las usando $ref.
Por exemplo, para a resposta comum a várias operações em que aparece uma lista de marcadores, eu defino um BookmarkListResponse sob components > responses:
components:responses:BookmarkListResponse:description: Lista de marcadorescontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
E então, eu a referencio em diferentes operações, como get-public-bookmarks:
yamlCopy code
/public/bookmarks:get:summary: Retornar uma lista de marcadores públicos usando parâmetros de consulta.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"
Note o locationQueryParam mencionado acima. Ele é definido sob components > parameters e referenciado em vários lugares na especificação da API, incluindo o exemplo mostrado acima.
8. Adicione Exemplos para Clareza
Você pode adicionar exemplos a parâmetros, propriedades e objetos para tornar a especificação do seu serviço Web mais clara. Exemplos podem ser lidos por ferramentas e bibliotecas para sua API. Por exemplo, uma ferramenta de API mock pode usar valores de exemplo para gerar solicitações simuladas. Você pode especificar exemplos para objetos, propriedades individuais e parâmetros de operação usando as chaves example ou examples.
Por exemplo, você pode ter valores complexos como exemplos para um parâmetro de texto de pesquisa:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
Consulta de pesquisa (palavras separadas por espaços). Filtros especiais disponíveis:
* `lang:iso_language_code` - por exemplo, `lang:en` para inglês, `lang:es` para espanhol, `lang:de` para marcadores em alemão
* `site:site_URL` - por exemplo, retornar marcadores de [www.codepedia.org](htt
