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

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.