Documentando a API

Dando continuidade à criação da documentação da API, vamos inicialmente verificar o retorno do GET de usuários. É possível ver que está sendo retornada a lista de todos os usuários cadastrados. No entanto, há informações que não devem ser retornadas, por serem informações confidenciais ou de tratamento interno.

Tratando os dados de retorno

Antes de retornar à lista de todos os usuários e todas as informações contidas em cada um, é interessante fazer um tratamento desses dados coletados e retornar somente as informações desejadas. Então, no arquivo de 'usuario.rota.js' crie uma função para preparar os dados, como abaixo:

function prepararResultado(usuario){
  const result = Object.assign({}, usuario)
  if (result.createdAt) delete result.createdAt
  if (result.updatedAt) delete result.updatedAt
  if (result.senha) delete result.senha
  return result
}

Após criada a função, no mesmo arquivo, navegue até a rota mencionada acima e adicione a preparação dos dados antes de retorná-los. O código da rota deve ficar como abaixo:

router.get("/", async (req, res) => {
  const usuarios = await Usuario.findAll();
  const resultado = usuarios.map(user => prepararResultado(user.dataValues))
  res.json({ usuarios: resultado });
});

Ainda nas rotas de usuário, existe a rota que busca um usuário pelo id e essa rota retorna também todas as informações, sem tratamento de dados. Então, adicione a mesma preparação de dados e a rota deve ficar como abaixo:

router.get("/:id", async (req, res) => {
  const usuario = await Usuario.findByPk(req.params.id);
  if (usuario) {
    res.json({ usuario: prepararResultado(usuario.dataValues) });
  } else {
    res.status(400).json({ msg: "Usuário não encontrado!" });
  }
});

Agora, voltemos à documentação.

Iniciando a documentação

Para iniciar a documentação, acompanhe a aula e veja a organização do arquivo. Após isso, vamos trabalhar na parte inicial do arquivo, inserindo informações e alterando alguns dados que vieram por padrão. Ao final, seu arquivo deverá estar assim:

openapi: '3.0.2'
info:
  title: IMD Blog API!
  version: '1.0'
  description: API do blog do IMD
  contact:
    name: Gustavo Leitão
servers:
  - url: http://localhost:8080/api
    description: Servidor de teste
paths:
  /test:
   get:
      responses:
         '200' :
          description: OK

Feita essa parte inicial, passaremos a documentar os paths da API.