Blog

Documentação de REST API com Swagger 2.0


O Swagger é um framework open-source, popular no mundo por realizar a sustentação do ecossistema de RESTful webservices. É composto por um conjunto de ferramentas para realizar o design, desenvolvimento, teste e documentação de APIs.

Compartilhe

Facebook Twitter Google LinkedIn

1. Introdução

No contexto de sistemas distribuídos, notamos uma constante evolução em como as aplicações realizam a integração e intercâmbio de dados, o compartilhamento de recursos computacionais e processam seus modelos de dados rígidos em tecnologias heterogêneas. Na linha do tempo, situamo-nos no momento onde encontramos uma abordagem mais moderna com webservices SOAP (Simple Object Access Protocol), que disponibiliza um protocolo estruturado para troca de dados em plataforma descentralizada e totalmente distribuída. Sendo este protocolo apenas uma estrutura composta por um envelope definido com header e body; que trafega sobre outros protocolos da camada de aplicação (modelo OSI), entretanto comumente utiliza servidores HTTP.

O SOAP é baseado em linguagem XML (Extensible Markup Language), que define uma estrutura bem-definida de dados; também aborda a infra-estrutura de descrição de serviços web baseado em WSDL (Web Service Description Language), que representa de forma completa como o serviço é definido e seus modelos de dados relacionados, ou seja, expõe o contrato do serviço. Com isso temos a disposição uma estrutura de descrição de serviço, especificando operações disponíveis e como acessá-las; utilizado para consumir o serviço, ou seja, define como integrar a aplicação através de dados estruturados em XML, como mecanismo de troca de dados o protocolo SOAP sobre HTTP.

Com webservices SOAP e XML, temos uma documentação de serviço provida de forma programática, complementada com uma documentação descritiva, porém  opcional, de como consumir o serviço, como processar e manipular os erros, e consequentemente como estruturar e validar o modelo de dados através de XSD (XML Schema Definition) antes mesmo de realizar a conexão com o serviço.

Esta tecnologia fora muito difundida no mundo por volta do ano de 2000, conforme o relato fornecido por Don Box, um dos criados do protocolo. Nos dias atuais, ainda encontramos muitas aplicações que utilizam esta abordagem de intercâmbio de dados para processamento descentralizado e distribuído. Entretanto como toda tecnologia, nos deparamos com seus efeitos colaterais e, consequentemente, a evolução para outros meios de integração de aplicações e estruturação de modelos de dados.

O estilo arquitetural distribuído REST (Representational State Transfer) fora apresentado e definido na dissertação de doutorado de Roy Fielding, publicada no ano de 2000, apresentando significativas qualidades para sistemas distribuídos de larga escala e utilizado em grande parte para desenvolver a arquitetura moderna da Web. Com isso, temos: 1) identificação de todos recursos através de um mesmo mecanismo global, representado por uma URL (Uniform Resource Locator); 2) padronização e uniformização da interface de comunicação, através de um conjunto de métodos pré-definidos: GET, POST, PUT, DELETE, HEAD, PATCH; 3) interações totalmente stateless, com representação de estado através de um conjunto bem-definido de recursos, onde o servidor não mantém dados sobre as sessões de clientes em memória.

Por meio de webservices baseados em REST ou comumente denominados  webservices RESTful, é permitido acessar e manipular a representação de recursos em um conjunto pré-definido e uniforme de operações sem estado (stateless), por meio de uma identificação global. A iteração com um recurso é realizado através de operações genéricas do protocolo HTTP, ou seja, para um mesmo recurso disponibilizado em uma URL normalizada, temos a disposição todos os métodos genéricos, sendo cada um processado e interpretado conforme sua especificidade.

Para um maior entendimento, podemos tomar como base a URL (identificação global) http://api.researchlabs.com.br/v1/company, configura explicitamente um recurso company, a semântica de representação de dados está relacionada ao nível de infraestrutura, e pode ser acessado pelos verbos HTTP da seguinte forma:

  1. GET: acessa a lista de companies e outros detalhes da coleção.
  2. GET/{id}: retorna a representação de um objeto único contido em uma coleção, acessado por identificador único ao final da URL, expressado pelo endereço - http://api.researchlabs.com.br/v1/company/25415210.
  3. POST: cria uma nova representação do recurso na coleção, deve-se informar no corpo da requisição a respectiva estrutura de dados, sendo retornado automaticamente pela operação o objeto persistido.
  4. PUT/{id}: atualiza a representação do recurso na coleção, composto por identificador único ao final da URL, complementado por sua respectiva estrutura de dados no corpo da requisição, caso não exista, o recurso é criado.
  5. DELETE/{id}: remove a representação de um recurso na coleção, composto por identificador único ao final da URL.

Conforme Roy Fielding [2000], componentes REST executam ações sobre um recurso utilizando sua representação para capturar o estado atual ou pretendido, distribuindo-o entre diversos componentes. Com a simplificação e padronização de como serviços web são definidos e escritos através da arquitetura REST, nosso questionamento é direcionado para: 1) como documentar os modelos de dados, que podem ser representados por payloads, em sua maioria, em formato de dados XML ou JSON (JavaScript Object Notation); 2) o que executa cada verbo HTTP sobre determinado recurso exposto; 3) como deve ser estruturada nossa requisição, como processamos o retorno da mesma e manipulamos os eventuais erros; 4) como publicamos nossa documentação da API REST de forma programática, conforme visto em descritivos WSDL.

Para efeito de claro entendimento, a denominação REST é considerada um padrão arquitetural, enquanto SOAP é a definição de um protocolo. Observa-se atentamente que REST não específica ou representa um padrão, mas utiliza de vários padrões estabelecidos no mercado para operar sua implementação.

O objetivo deste artigo é apresentar as principais definições de REST APIs e de como documentá-la de forma consistente e profissional utilizando o conjunto de ferramentas disponibilizadas pelo projeto Swagger, assim como utilizar a especificação OpenAPI. A abordagem prática é realizada através de projeto Java Spring Boot Application.

2. Documentação de REST APIs

A documentação de REST APIs é necessária e importante, pois nela descrevemos como nossos serviços são disponibilizados e como podem ser consumidos de forma correta. A descrição deve abordar a princípio, os detalhes dos recursos, como acessar sua URL, operações disponíveis e como trabalhar com os verbos HTTP, os modelos de dados relacionados, o content-type de request e response, dentre outros detalhes relevantes.

Há dois momentos distintos que podemos documentar webservices RESTful, antes de implementar o serviço, conhecido como Contract-First ou API-First, sendo que documenta-se a REST API antes de efetivamente implementá-la, por consequência é exposto um contrato de serviço apenas com a definição da interface para desenvolvedores interessados realizarem previamente seus testes de aceitação e integração com dados bem próximos do que serão providos em ambiente de produção, com possível geração de código-fonte esqueleto, tanto do lado cliente quanto do servidor. Outra forma é implementar todo o serviço para depois se preocupar em documentar, modelo conhecido como Contract-Last.

Em ambos os modelos podemos programaticamente gerar a documentação, automatizar completamente a tarefa de documentação, ou seja, assim que disponibilizamos ou modificamos um determinado recurso já criamos ou atualizamos a respectiva representação de documentação, gerada em tempo de compilação.

3. Introdução ao Swagger

O Swagger é um framework open-source, popular no mundo por realizar a sustentação do ecossistema de RESTful webservices. É composto por um conjunto de ferramentas para realizar o design, desenvolvimento, teste e documentação de APIs.

Em conjunto com as ferramentas temos a especificação OpenAPI que define uma interface padrão, independente de linguagem de programação para REST APIs, que provê tanto para computadores quanto para desenvolvedores um mecanismo para entenderem as capacidades do serviço, sem acesso direto ao código-fonte e sem necessidade de acesso aos recursos através de comunicação em rede.

A OpenAPI é suportada pela Linux Foundation, com a chancela da Open API Initiative. Originalmente era conhecida como Swagger Specification, com desenvolvimento iniciado no ano de 2010 por Wordnik, com a compra em 2015 pela SmartBear Software e consequente doação para o novo grupo criado o Open API Initiative com o suporte de várias empresas do setor e patrocinado pela Linux Foundation. Atualmente conta com um ecossistema de ferramentas vasto para o suporte de RESTful webservices, as principais abordadas neste artigo são apenas as duas primeiras, conforme:

  • Swagger Editor - editor online utilizado no design e definição de contratos de serviços disponibilizados via API, com validação de documento em tempo-real. Exibe documentação em HTML conforme especificado via YAML (YAML Ain’t Markup Language).
  • Swagger UI - publicação de documentação de referência em formato HTML de todos os serviços e recursos da REST API, renderizado automaticamente a partir de documento JSON ou YAML por Javascript, apresenta os recursos disponibilizados de forma compreensível, pois provê mecanismo de interação com o serviço via interface gráfica.
  • Swagger Codegen - geração de código-fonte de forma rápida em diversas linguagens de programação (tais como Java, Javascript, Scala, Python, PHP, Ruby, etc), simplifica o processo de geração de esqueletos de código tanto para camada servidor quanto para cliente, através da especificação OpenAPI.

Adotamos a utilização das ferramentas Swagger Editor e UI através de um projeto Java Spring Boot Application, modelando a API com as melhores práticas de mercado por Contract-First, ou seja, geração de documentação RESTful webservices a partir de uma implementação existente. O projeto Java é denominado WPLEX-Garagem que controla o cadastro de empresa, de garagem e consulta de garagens vinculadas a determinada empresa. Todas as ferramentas do Swagger utilizadas são instaladas localmente em ambiente de desenvolvimento, que posteriormente pode ser utilizado como um guia de referência para instalação de ambiente em de produção.

3.1 Instalação do Swagger Editor - Design de API

Swagger Editor
Figura 1 - Swagger Editor

O Swagger Editor é um editor online que executa uma aplicação NodeJS em container web que nos auxilia na criação e manutenção do arquivo de especificação do Swagger que representa nossa REST API. No editor podemos importar um arquivo JSON e convertê-lo em YAML automaticamente, realizar download do arquivo editado em JSON e YAML. Para iniciar a documentação, caso não possua domínio da sintaxe YAML, o editor online exibe um modelo de documentação que pode ser utilizado como base para a definição de contratos de serviços REST; conforme definimos o serviço, do lado direito do editor é renderizado em tempo real a documentação em HTML, com validação de sintaxe.

Para modelar uma REST API podemos acessar a versão online do editor no endereço  http://editor.swagger.io/ ou realizar a instalação localmente. Preferencialmente iremos optar por instalar o editor localmente em nosso ambiente de desenvolvimento.

Em ambiente unix-like execute os comandos na sequência:

sudo apt-get install nodejs-legacy
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm start
 

No terminal, ao executar o comando npm, um servidor estático é disponibilizado, conforme informação apresentada abaixo:

> swagger-editor@3.0.0 start /home/username/git/swagger-editor
> npm-run-all --parallel serve-static open-static
> swagger-editor@3.0.0 open-static /home/username/git/swagger-editor
> node -e 'require("open")("http://localhost:3001")'
> swagger-editor@3.0.0 serve-static /home/username/git/swagger-editor
> http-server -i -a 0.0.0.0 -p 3001

Starting up http-server, serving ./
Available on: http://127.0.0.1:3001  -  http://192.168.0.42:3001
 

Para acessar o editor online execute o browser e digite o endereço http://127.0.0.1:3001.

3.2 Instalação do Swagger UI - Documentação de API

Swagger UI
Figura 2 - Swagger UI

O Swagger UI é uma ferramenta visual que analisa arquivos YAML ou JSON que seguem a especificação OpenAPI e renderiza documentação em HTML amigável, sendo possível navegar e interagir com o serviço exposto através de requests reais gerados através da interface gráfica (utiliza sintaxe curl). Temos a disposição uma versão online apenas para avaliação, que é uma demonstração de como pode ser estruturado e renderizado uma documentação de RESTful API, disponível no endereço http://petstore.swagger.io/.

Assim como fizemos com o editor, iremos realizar a instalação do Swagger UI em ambiente de desenvolvimento, contudo essa ferramenta faz uso do gerenciador de containers Docker, assim sendo, temos o pré-requisito de instalá-lo.

Para realizar a instalação do Docker, em ambiente unix-like, siga os seguintes passos:

sudo apt-get update
sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
sudo apt-add-repository 'deb https://apt.dockerproject.org/repo ubuntu-xenial main'
sudo apt-get update
apt-cache policy docker-engine
sudo apt-get install -y docker-engine
sudo systemctl status docker
 

Agora que temos o Docker instalado e sendo executado em ambiente unix-like, vamos executar o Swagger UI, conforme:

git clone https://github.com/swagger-api/swagger-ui
cd swagger-ui
sudo docker pull swaggerapi/swagger-ui
sudo docker run -p 8087:8080 swaggerapi/swagger-ui
 

Outra opção é instalar o Swagger UI sem o pré-requisito de instalar o docker-engine no ambiente de execução da ferramenta, pois somente é necessário um container web para hospedar a documentação. Como o projeto Spring Boot Application executa sobre o Apache Tomcat, utilizaremos o mesmo para expor a documentação de forma pública.

Conforme será visto no tópico 3.3, veremos que ao compilar o projeto Java é gerado de forma automática um arquivo JSON que representa a documentação da REST API, ou seja, com o swagger-maven-plugin processamos todas as anotações da Open API presentes no código-fonte e fornecemos o referido arquivo para renderização dos detalhes da documentação em HTML. Localize no sistema operacional o diretório %CATALINA_HOME%/webapps e copie o diretório ‘dist’ do Swagger UI, com isso temos o UI executado em ambiente de desenvolvimento.

Apenas para efeito de ilustração e entendimento, em nosso projeto Spring Boot, padronizamos o acesso de forma pública da documentação da REST API do projeto, sendo acessado através da seguinte estrutura de URI - http://<domain>/project-name/api-portal/swagger/1.0/index.html.

4. Conclusão

Conforme podemos observar nos dias atuais, o processo de desenvolvimento de software utiliza o desenho de solução baseado em um estilo arquitetural voltado a decomposição de regras de negócios em serviços, mais especificamente em REST APIs, que consolidou-se no mercado global como um padrão de comunicação e distribuição de processos em ambientes críticos. Com isso, a necessidade de padronizar a forma como é documentado os contratos públicos e seus respectivos modelos de dados se fez necessário, representado por um consórcio de empresas que define e discute o futuro de uma especificação aberta, denominada OpenAPI Specification.

Como toda especificação, a mesma carrega consigo em sua órbita ferramentas para automatizar processos, mais especificamente para a geração de documentos baseados em JSON ou YAML que descrevem a interface de REST APIs originados por anotações realizadas sobre os contratos de serviços de forma amigável e produtiva.

Com isso deixamos nossas documentações mais próximas da implementação e constantemente atualizadas, pois vemos que ambas caminham juntas e detem um ciclo de vida único, facilitando a manutenção e publicação de atualizações vinculadas a processos de build; voltada para desenvolvedores e interessados em consumir e entender de forma completa e descritiva como integrar suas aplicações com os serviços disponibilizados em nosso parque tecnológico de REST APIs.

Referências

[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf

[2] https://github.com/OAI/OpenAPI-Specification

[3] https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

[4] http://kongchen.github.io/swagger-maven-plugin/

[5] https://github.com/kongchen/api-doc-template

[6] https://smartbear.com/product/swaggerhub/overview/

[7] https://github.com/swagger-api/swagger-editor

[8] https://github.com/swagger-api/swagger-ui

[9] https://github.com/swagger-api/swagger-codegen

[10] https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf

[11] https://blog.philipphauer.de/enriching-restful-services-swagger/

[12] https://blog.philipphauer.de/restful-api-design-best-practices/

Marcadores

REST API Swagger JSON YAML WADL OpenAPI WebService JAX-RS RESTFul URI API Documentation Schema Definition API Operation API-First Contract-Last

Não perca mais nenhum artigo!

Assine nosso blog e receba novos artigos diretamente em seu e-mail.