How to automate documentation of REST APIs (Jersey implementation)

Question

I wrote a fairly extensive REST API using Java Jersey (and JAXB). I also wrote the documentation using the Wiki, but it was a completely manual process that is very error prone, especially when we need to make changes, people tend to forget to update the wiki.

From a look around, most other REST APIs also manually create their documentation. But I am wondering if this might be a good solution for this.

Things to be documented for each endpoint:

• Service name
• Category
• URI
• Parameter
• Types of Parameters
• Response Types
• Response Type Scheme (XSD)
• Request and Response Examples
• Request Type (Get / Put / Post / Delete)
• Description
• Error codes that may be returned

And then, of course, there are common things in common, such as

• Security
• REST Review
• Error processing
• Etc

These general things are perfectly described once and do not require automation, but for the methods of the web service itself it seems highly desirable to automate it.

I thought about the possibilities of using annotations and writing a small program that generates XML, and then XSLT, which should generate the actual documentation in HTML. Does it make sense to use a custom XDoclet?

Any help would be greatly appreciated Alan

Answer 1

Swagger is a great option. This is a GitHub project, has Maven integration and many other features to maintain flexibility.

Integration Guide: https://github.com/swagger-api/swagger-core/wiki

Additional information: http://swagger.io/

Answer 2

Unfortunately, Darrell answers technically correctly, but this is a focus focus in the real world. This is based on an ideal that only a few agree, and even if you were very careful about it, there is a possibility that for some reason you can’t exactly match out of your control.

Even if you could, other developers who could use your API might not like it or find out the details of RESTful templates ... Remember that the point of creating the API is to make it easier for other users to use, and the documentation is required.

Achim's point about WADL is good. Since it exists, we should be able to create a basic tool for creating API documentation.

Some people took this route, and an XSL stylesheet for conversion was developed: https://wadl.dev.java.net/

Answer 3

Although I'm not sure if it fully suits your needs, take a look at enunciate . It looks like a good documentation generator for various web service architectures.

EDIT Mention available under github umbrella

Answer 4

You may be interested in Jersey's ability to provide a so-called WADL description for all published resources in XML format at runtime (automatically generated from annotations). This should already contain what you need for basic documentation. In addition, you can add additional JavaDoc, although this requires more configuration.

Please see here: https://jersey.java.net/documentation/latest/wadl.html

Answer 5

Darrell answers for sure. The description type should not be provided to REST API clients, as it will force the client developer to combine the client implementation with the current service implementation. This is what the restriction of the REST hyperlink seeks.

You can still develop an API that is described in this way, but you should be aware that the resulting system will not implement the REST architectural style and therefore will not have the properties (esp. Evolvability) guaranteed by REST.

Perhaps your interface might be a better solution than RPC. But keep in mind what exactly you are building.

Yang

Answer 6

I hate being the bearer of bad news, but if you feel the need to document the things you listed, then you probably haven't created a REST interface.

REST interfaces are documented by identifying a single root URL, and then by describing the type of presentation media that is returned from that URL, and all media types that can be accessed through the links in that view.

What types of media do you use?

Also add the link in RFC2616 in your docs. This should explain to any consumer how to interact with your service.

Answer 7

You can find the rest-tool . It follows a linguistic agnostic approach for writing specifications, mock implementations, and automated unit testing for the RESTful API.

You can use it only to document your APIs, but this specification can be immediately used to ensure the quality of the implementation of real services.

If your services are not yet fully implemented, but, for example, should be used by the web interface, the rest-tool provides instant mockery of the description of the service. checking the content schema (JSON schema) can also be easily added along with the documentation, and is also used by unit tests.