Investigate API documentation tools

[deruelle]

• Swagger2markup - https://github.com/Swagger2Markup/swagger2markup
• Spring REST Docs (works with any Java project, not just one based on Spring) - http://projects.spring.io/spring-restdocs/

The great part about these tools is that they test the code, automatically generate the docs, integrate with AsciiDoc and have strong communities of users.

[RobWin]

Hi,

do you want to use the OpenAPI Spec (Swagger)? Contract-first or Code-first? Or do you plan to develop a HATEOS Rest API?

[deruelle]

It will depend on the projects under https://github.com/RestComm, but most of them are code-first see https://github.com/RestComm/RestComm-Core/tree/master/restcomm/restcomm.http/src/main/java/org/mobicents/servlet/restcomm/http by example. What are the best practices here you would recommend ?

[RobWin]

Since you use JAX-RS and not Spring MVC, you can use this Maven Plugin to generate a Swagger (OpenAPI) Spec file from your source code.

You can use Swagger2Markup directly or its Maven Plugin to convert the Swagger Spec into AsciiDoc/Markdown.

Then use the AsciiDoctor Maven Plugin to convert the Swaggger AsciiDoc into HTML or PDF or EPUB.

[RobWin]

Result would look like this https://raw.githubusercontent.com/Swagger2Markup/swagger2markup/master/images/Swagger2Markup.PNG