Testando e Documentando RESTful APIs usando Spring REST Docs com Kotlin e Spring-Boot

Thiago Nogueira

Documentar APIs pode ser uma tarefa um tanto quanto trabalhosa, desde que não seja feita com o auxílio de alguma ferramenta/framework. As chances de uma documentação, ficar inconsistente/desatualizada, é enorme. Para evitar este cenário, existem algumas alternativas, como o Swagger e, o motivo deste post, Spring REST Docs.

Utilizo o Swagger em alguns projetos e aprecio seu uso, dado sua facilidade. Para quem não conhece, como documentar APIs usando Swagger, irei resumir. Você precisará incluir a dependência em seu Projeto e então configurar sua classe de application para habilitar o Swagger. Dada esta configuração, basta então incluir as anotações no seu Controller, para que seja gerada a documentação. Seguindo esta receita de bolo, primeiro é feita construção da API e posteriormente, ou até no mesmo momento, são adicionadas as anotações no código do Controller para a geração automática da documentação. Talvez seja o caso de escrever um outro post para exemplificar, mas é fácil encontrar exemplos no nosso amigo Google.

Se já temos o Swagger, por que utilizar Spring REST Docs?

A motivação para o uso do Spring REST Docs, foi devido a necessidade que encontrei em um projeto, de desenvolver APIs e incluir o teste de comportamento e a geração de documentação no mesmo processo. Dado o desenho/necessidade de uma API, podemos escrever o teste, juntamente com o contrato da mesma em forma de documentação. Seria uma forma de trabalhar o desenvolvimento com base nos testes.

Exemplo de teste usando Spring REST Docs

Além disto, o Spring REST Docs gera a documentação em um formato mais profissional, comparado ao uso do Swagger.

Exemplo da documentação gerada a partir do teste na imagem anterior

Imagina gerar a documentação de sua API, com este formato. Não seria mais elegante comparado ao uso do Swagger?

Veja também o exemplo da própria documentação do Spring REST Docs: https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

Vale lembrar, que o Spring REST Docs utiliza o Asciidoctor, como padrão.

Mão na massa

Para exemplificar o uso do Spring REST Docs, criaremos uma API de demonstração, com um CRUD simples de Produtos, usando Spring-boot com Kotlin. Gerar o projeto, é um passo simples, feito via https://start.spring.io/. Não se esqueça de adicionar as dependências Web e REST Docs, conforme abaixo:

Clique para gerar o Projeto, então descompacte e abra em sua IDE de preferência. Criaremos uma camada de Controller com os recursos do nosso CRUD de Produtos:

E uma camada de Serviço, que será necessária para explicar o uso de mock em nossos testes mais a frente:

Agora precisaremos adicionar a configuração necessária para o uso do Spring REST Docs. Basicamente, precisaremos adicionar dois plugins na sessão de plugins em nosso pom.xml

1 - asciidoctor-maven-plugin: Necessário para gerar e empacotar os Snipptes da nossa documentação.

2 - maven-resources-plugin: Necessário para copiar arquivo processado para o diretório generated-docs.

Feita a configuração, precisaremos construir o cenário para o teste desejado, incluindo neste ponto, a documentação que desejamos criar.

Testando nosso Controller e documentando com o Spring REST Docs

Repare no setup necessário, para que a documentação seja gerada. Além disto, veja o cenário de teste, onde é feito o uso do Mockito, para mockar nossa camada de Serviço. Após, construimos a chamada e adicionamos o detalhamento dos parâmetros e campos envolvidos no request.

Após a construção da classe, podemos executar o teste e então visualizar os snippets gerados pelo Spring REST Docs no diretório target com o nome da nossa classe de teste e nome do cenário de teste.

A partir disto, podemos então customizar nosso arquivo src/main/asciidoc/index.adoc, incluindo os snippets e organizando da maneira que melhor entendermos.

Com base nos plugins, isto será convertido em um arquivo index.html que ficará disponível em nosso controller, no path: http://localhost:8080/docs/index.html

Vejo o código do nosso index.adoc: https://gist.github.com/thiagotn/556fd14584c01cd00141910b019d99f8

Após este ponto, já poderemos realizar a construção e execução do projeto:

mvn clean install

mvn spring-boot:run

Acesse http://localhost:8080 e este deverá ser o resultado:

Gostou? O código-fonte completo deste exemplo, está disponível aqui. Fique a vontade para compartilhar e melhorar.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade