DevOps - Swagger no Docker

A mais popular API Framework do Mundo é isso que diz o site oficial do Swagger, e pode parecer incrível mas não duvido nem um pouco que isso seja verdade. Nunca vi um Framework acender tão rápido quanto o Swagger ao gosto popular. Em termos simples o Swagger é uma especificação aberta para definição de API REST. É uma especificação na qual é possível descrever, produzir, consumir, testar e visualizar uma API RESTful API. Sua grande vantagem foi prover um conjunto com 3 ferramentas:

• Swagger-Editor - cuida da parte de projeto
• Swagger-Build - trabalha com construção (em várias linguagens) tanto do servidor (que proverá os serviços) quanto do cliente (que consumirá)
• Swagger-Ui - responsável pela documentação online através do arquivo padrão do Swagger que pode ser no padrão JSON ou YAML.

Neste artigo pretendo mostrar como instalar e utilizar o Swagger-Editor e Swagger-UI através do Docker, porém sem entrar em qualquer detalhes sobre ambos. A documentação é muito vasta e já existem vários tutorias na Internet de como utilizá-lo. Vamos então para a parte prática.

Instalação

Primeiramente temos que subir e executar (não simultaneamente) 2 imagens a do editor:

$ docker pull swaggerapi/swagger-editor
$ docker run -d --name swaggereditor -p 80:8080 swaggerapi/swagger-editor

E a do documentador:

$ docker pull swaggerapi/swagger-ui
$ docker run -d --name swaggerui -p 80:8080 swaggerapi/swagger-ui

Visualização

Agora vem a parte da visualização dos serviços, para usar o Editor é muito simples, basta iniciar a imagem e utilizá-lo na porta 80 com o endereço http://localhost:80. Porém após criar um arquivo se desejar ver seu resultado no Documentador será necessário habilitar um servidor para isso.

1. Instalar globalmente o pacote http-server:

$ sudo npm install -g http-server

2. Na pasta do arquivo ativar o server com o parâmetro CORS (isso evita o erro Access-Control-Allow-Origin):

$ http-server --cors

3. Abrir o seguinte endereço no Swagger UI:

http://localhost:8080/[nome].json ou .yaml

Bem é isso, deixei a sua disposição um vídeo no meu canal do YouTube que mostra todos os passos para baixar e começar a usar o Swagger que como diz sua tradução no dicionário: "Swagger é andar ou agir de uma forma que mostra confiança ou importância".

Obrigado e até a próxima
Fernando Anselmo