Devemos fazer um rota e já documentar mesmo que descubramos falhas posteriormente? Daí vai atualizando a documentação em paralelo?
Devemos fazer um rota e já documentar mesmo que descubramos falhas posteriormente? Daí vai atualizando a documentação em paralelo?
Olá, Luidi! Tudo joia?
É uma ótima prática documentar as rotas da API assim que elas são criadas, mesmo que haja a possibilidade de encontrar falhas no futuro.
A documentação inicial ajuda a manter a equipe alinhada e facilita a comunicação sobre como a API deve funcionar. Além disso, ela é uma ferramenta valiosa para qualquer desenvolvedor que venha a trabalhar no projeto posteriormente.
No caso de encontrar falhas ou realizar alterações, a documentação deve ser atualizada em paralelo. Isso garante que todos os envolvidos no projeto tenham acesso à informação mais recente e que a API esteja sempre bem documentada. Ferramentas como o Swagger são muito úteis nesse processo, pois permitem gerar uma documentação interativa que pode ser facilmente atualizada conforme necessário.
Espero ter ajudado e bons estudos!
E na documentação feita com o Swagger é bom que tenha mensagens de erro para cada erro de validação? Não ficaria muito grande? Tipo: "O email não pode ter letras maiúsculas", "o email não pode começar com número", "o email não pode ter 2 '@'", "o email não pode terminar sem extenção como '.com', '.br', etc", etc. Oq me assusta é que tem várias validações q devem ser feitas e muitas vezes vou fazer tipo a verficação do email e esquecer outras, ou ter q mudar, etc. A formação até aqui não ensinou como fazer essas validações completas, focou mais na lógica. Tem uma formação mais pra frente q aborda os temas das validações completas de "email", "nome", "senha", "cpf", "cnpj", etc?
Oi, Luidi!
Sobre sua última dúvida: o problema pode estar nesse ponto — você não precisa documentar cada detalhe minúsculo de validação no Swagger. O ideal é documentar apenas os cenários de erro que fazem sentido para a API como contrato, como:
Para validações detalhadas como regras específicas de email, CPF, CNPJ, senha etc., o que você deve fazer é centralizar tudo em uma única resposta de erro, normalmente algo como:
{
"erro": "Dados inválidos",
"detalhes": [
"O email não pode ter letras maiúsculas",
"O email deve conter apenas um '@'"
]
}
Assim, a documentação não cresce de forma exagerada e você não precisa atualizar manualmente cada combinação de erro.
Além disso:
✔ Swagger não é lugar para ensinar validação — é para descrever o contrato da API.
✔ As validações detalhadas ficam no código, e ele retorna mensagens que o Swagger apenas exemplifica.
Sobre sua pergunta final: sim, mais adiante você encontrará formações que abordam validações completas com bibliotecas como class-validator, Joi, Yup, Zod, etc., e também validações de documentos brasileiros.
Fico à disposição.
"Para validações detalhadas como regras específicas de email, CPF, CNPJ, senha etc., o que você deve fazer é centralizar tudo em uma única resposta de erro, normalmente algo como:", então na minha API eu não devo informar qual foi o erro específico que ocorreu na validação de email por exemplo? Caso ocorra o erro eu não devo falar que ocorreu o erro pois colocou 2 "@" ou porque faltou a extensão tipo ".com" ou pq foi usado letras maiúsculas, etc? Eu devo só colocar uma mensagem de erro dizendo tudo que não pode? Mas daí não ficaria enorme, pois são muitas validações.
Ou eu devo centralizar colocando todos os tipos de erro somente na documentação do Swagger e na API fazer aparecer a mensagem de erro adequada para cada situação? Se for isso, como se faz? Pode dar um exemplo caso esse for o caso?
Eu perguntei pro ChatGPT: "Então no Swagger quando der erro de validação q é o "422" eu devo informar dentro do "detalhes" todos os erros de validação possível? Pois quando ocorrer qualquer erro de validação vai ser mostrado essa mensagem com o "detalhes" informando todos os erros de validação que podem ter ocorrido. Sendo assim o Swagger não vai indicar qual o erro específico de validação ocorreu mas mostrar quais podem acontecer. É isso?"
Resposta do ChatGPT:
Oq o ChatGPT respondeu tá certo?
Bom dia, Luidi!
Sim, O ChatGPT está certo! Não tem porque você adicionar tantos exemplos de erros para uma determinada rota, mesmo que nessa rota você tenha deixado vários tipos de tratamentos.
Acontece que o Swagger é uma documentação de rotas principalmente usada como um acesso facilitado, por exemplo, um Front-end usando uma documentação do Swagger já teria tudo o que é necessário para consumir as rotas no Front, ele não precisa saber todos os casos de erro para isso.
Agora, em uma documentação oficial, escrita em uma página completamente externa ao Swagger, cabe adicionar toda essa descrição.
Fico à disposição!