Generating REST API Documentation from Restlet annotations

Question

The RESTful Web service APIs are implemented using Restlet. I need to generate the API documentation for these. Rather than starting with a separate document, I am evaluating if this can be generated from the source code annotations itself.

I looked at Swagger and enunciate. Swagger seems to be based on the JAX-RS specification. Enunciate looked a little more promising as there is an FAQ that mentions how to generate for non JAX-RS implementations but there is no help.

1. Are there any tools (or if the community has used any) for generating API documentation from Restlet annotations?

2. Has anyone integrated Restlet with enunciate for generating documentation?

Answer 1

Restlet now supports the ability to generate either corresponding Swagger and RAML contents based your application at runtime.

Following docs could help you:

• For Swagger (extension org.restlet.ext.swagger): see http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/swagger
• for RAML (extension org.restlet.ext.raml): see http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/raml

You can then leverage tools from the tool community to generate your API documentation. You could consider Swagger UI that is a great tool to display online what an API provides and interact with it.

Hope it helps you, Thierry