Tutorial de documentação de API com Swagger para iniciantes - 1 - Introdução à documentação de API com Swagger

O que é Swagger?

O objetivo do Swagger™ é definir uma interface padrão, independente de linguagem, para APIs REST, permitindo que humanos e máquinas descubram e entendam as capacidades de um serviço sem acesso ao código-fonte, documentação ou inspeção do tráfego de rede. Quando bem definido pelo Swagger, um consumidor consegue entender e interagir com o serviço remoto com uma lógica de implementação mínima. Assim como as interfaces fizeram na programação de baixo nível, o Swagger elimina as dúvidas ao chamar um serviço.

Tecnicamente falando, o Swagger é uma especificação formal cercada por um vasto ecossistema de ferramentas, que inclui desde interfaces de usuário front-end, bibliotecas de código de baixo nível até soluções comerciais de gestão de APIs.

Como começar?

Se você é um provedor de APIs e quer usar o Swagger para documentar suas APIs, há várias abordagens disponíveis:

Uma abordagem *top-down*, onde você usa o Swagger Editor para criar sua definição Swagger e depois utiliza as ferramentas integradas Swagger Codegen para gerar a implementação do servidor.
Se o