O Swagger é uma ferramenta voltada principalmente para desenvolvedores. Assim como o motor de um carro, ele exige conhecimento técnico para ser compreendido e mantido. Quando há necessidade de verificar ou ajustar o motor, não se consulta qualquer pessoa — leva-se o carro a um mecânico, que, em tese, sabe o que está fazendo. O mesmo princípio se aplica ao Swagger: ele deve ser utilizado por quem entende da estrutura e funcionamento da API.
Documentar excessivamente no Swagger, incluindo até o que é óbvio, pode gerar ruído. Quando tudo é documentado indiscriminadamente, o que realmente importa pode se perder no meio de tanta informação. Isso compromete a utilidade da documentação, tornando difícil identificar o que é relevante e o que não é.
Portanto, é essencial encontrar um equilíbrio: documentar o necessário, com clareza e objetividade, para que a documentação seja útil e mantenha seu propósito técnico.
Top comments (0)