2

I want to automatically document my REST-API. I know, there are many tools for that, but I want to generate the documentation from my unit tests.

The reason for this is, that I want the documentation to mirror, what is tested and what not. Nevertheless the documentation should be as rich as a documentation generated by let's say swagger.

I already found two projects with this approach, doctester and testdoc4j. Both do not satisfy my needs. The resulting documentation does not aggregate the happy path and the error paths.

What tools do you use and can you suggest any good one?

Cheers.

Edit:

There is a difference between documenting the API contract, defined in the interface, and documenting the test scenarios. If my documentation only includes the tested endpoints and pathes, I am able to define my interface and can hand out only the portions, I have tested.

This means I am able to define an interface with let's say ten endpoints. After implementing a basic functionality with corresponding tests, I can release this part with documentation. Not yet stable or implemented endpoints are not included, which prevents the users from using them.

tgr
  • 3,557
  • 4
  • 33
  • 63

4 Answers4

0

Perhaps you want a BDD framework? Eg:

lance-java
  • 25,497
  • 4
  • 59
  • 101
  • No, I thought about that, but this is not what I want. They are not a suitable tool for API documentation and are not able to include the sent request and the received response. – tgr Feb 26 '16 at 10:26
0

I recently did some research about the same topic and decided to use the free version of Miredot because it is the only tool that fulfilled my requirements:

  1. Does not need extra annotations. All information is extracted from JavaDoc
  2. Can handle JAX-RS as well as Spring annotations
  3. Easy maven integration

Miredot generates automatically a HTML based documentation when you run mvn test

eztam
  • 3,443
  • 7
  • 36
  • 54
  • You are right, the documentation is generated in the test step, but it refers to the contract definition and not the tests. – tgr Feb 26 '16 at 11:28
  • 1
    Miredotter here.. Just to confirm. Miredot hooks into the maven lifecycle after the compilation step. Running `mvn test` ensures Miredot runs as well. We only look at code, annotations and Javadoc, not tests. – bertvh Mar 03 '16 at 13:51
0

Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.

Integration guide: swagger-core wiki

More Information: here

P S M
  • 1,121
  • 12
  • 29
  • You are right, swagger generates a well structured documentation, but it is not from the tests. It takes the interface as source of documentation, which is a big difference. Swagger documents the contract, whereas I want a documentation of the actually tests cases. – tgr Feb 26 '16 at 10:28
0

Not sure if you have already found something for this, but Spring RestDocs does exactly what you are asking about here.

https://spring.io/projects/spring-restdocs

Im curious as to other tools you may have run across in other languages too.

shinjw
  • 3,329
  • 3
  • 21
  • 42