domingo, 2 de abril de 2017

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