Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to automate documentation of a REST API (Jersey Implementation) [closed]

I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.

From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.

The kind of things which need to be documented for each endpoint are:

  • Service Name
  • Category
  • URI
  • Parameter
  • Parameter Types
  • Response Types
  • Response Type Schema (XSD)
  • Sample requests and responses
  • Request type (Get/Put/Post/Delete)
  • Description
  • Error codes which may be returned

And then of course there are some general things which are global such as

  • Security
  • Overview of REST
  • Error handling
  • Etc

These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.

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

like image 511
Alan Mc Kernan Avatar asked Nov 11 '09 09:11

Alan Mc Kernan


People also ask

How do I document API with Swagger?

Head over to Swagger Inspector, and insert the end point of the resource you want to have documented. You can then navigate to the right panel from the History section of Swagger Inspector, and click "Create API definition" to create the OAS definition.

What is Jersey in REST API?

Jersey is Sun's production quality reference implementation for JSR 311: JAX-RS: The Java API for RESTful Web Services. Jersey implements support for the annotations defined in JSR-311, making it easy for developers to build RESTful web services with Java and the Java JVM.


1 Answers

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: https://github.com/swagger-api/swagger-core/wiki

More Information: http://swagger.io/

enter image description here

like image 104
Webnet Avatar answered Sep 21 '22 15:09

Webnet