Documentação de API

https://devsuperior.com.br
Objetivo
● Apresentar uma breve introdução sobre documentação de API
● Utilizando a especificação OpenAPI vamos documentar a nossa
API usando as ferramentas Swagger e ReadMe.
Agenda
● Introdução
● Ferramentas
Introdução
Definição

Documentação é uma representação, normalmente textual

que descreve os principais aspectos de um determinado
produto ou serviço, permitindo a consulta e validação das
partes envolvidas.
Introdução
Por quê documentar uma API?
● Auxiliar os usuários desta API a entenderem seus recursos;
● Abstrair detalhes da API;
● Servir de referência para o time;
Introdução
Formas de se documentar
● Documentação Manual
○ Recomendada para pequenas APIs; (Ex: readme github)
○ Em sistemas maiores, este processo é muito trabalhoso e demorado.

● Documentação à partir de ferramentas

○ Agiliza o processo de documentação;
○ API sempre atualizada
○ Padronização na documentação
Introdução
Especificações de documentação
● Define um conjuntos de regras que vão guiar o processo de
documentar a API:
○ Descrição da funcionalidade;
○ Parâmetros de entrada que são utilizados;
○ Formato da requisição/resposta;
○ Status code esperado;
○ Requerimento ou não de autenticação.
Introdução
Especificações de documentação
● Quando falamos de REST API, a principal especificação é o
OpenAPI.
Ferramentas
● Nas próximas aulas vamos apresentar duas ferramentas:
○ Swagger
○ Readme