REST API Documentation Using JAXRS-ANALYZER

API documents are technical catalogs. These catalogs are instructions created by developers on how to request service from a specific system or platform. API documents contain definitive technical guides on how to locate services, construct requests and what to expect as the response.

Need for these sort of documentation gets bolder in an N-Tier application development environment where multiple programmers develop separate tiers (sub-systems) of a larger system. Sub-systems communicate with each other using interoperability technologies such as web services. Considering a web service end-point (SOAP or REST), besides any WSDL or WADL, there is always a need to have a well-designed API documentation accompanying the service interface. Each team’s developers provide API documentation for the service interface their system provides to the world.

During the past two years, I have used REST technology as the main web service technology in my projects. Creating API documents for the web service endpoint was consisted of documenting every single web service method (REST resource paths), input/output content types (content type negotiation) and describing how the resources could be acquired if the resource paths were not self-describing. There was always a need to have a mechanism in place to automatically create such documentation and keep it up to date with web service interface changes.

About a month ago, I read about a JAX-RS based community project called JAXRS-ANALYZER developed by Sebastian Daschner. JAXRS-ANALYZER uses byte code analysis to create API documentation for java based RESTful projects in Plaintext, Swagger and AsciiDoc formats. By using bytecode analysis, there is no need to use any annotation or do any additional coding in the project to use this tool. Analyzer could be used as maven plug-in or as a standalone tool.

To demonstrate how JAXRS-ANALYZER works as an automatic API documentation generator in java based RESTful projects, consider the following simple REST resource:

@Path("/sample")
public class WebService {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getMethod() {
        return "Hello world !";
    }

    @POST
    @Consumes(MediaType.TEXT_PLAIN)
    public String postMethod(String content) {
        return "Received : " + content;
    }

    @POST
    @Path("entity/cosumer")
    @Consumes(MediaType.APPLICATION_JSON)
    public String postMethod2(Sam sam) {
        return "Hello : " + sam.getName();
    }

    @GET
    @Path("entity/preview")
    @Produces(MediaType.APPLICATION_JSON)
    public Sam postMethod3() {
        Sam sam = new Sam();
        sam.setName("sam");
        sam.setFamily("sepassi");
        return sam;
    }
}

To use analyzer as maven plug-in, the following entry have to be added to pom.xml:

<plugin>
    <groupId>com.sebastian-daschner</groupId>
    <artifactId>jaxrs-analyzer-maven-plugin</artifactId>
    <version>0.9</version>
    <executions>
        <execution>
            <goals>
                <goal>analyze-jaxrs</goal>
            </goals>
            <configuration>
                <!-- Available backends are plaintext (default), swagger and asciidoc -->
                <backend>plaintext</backend>
            </configuration>
        </execution>
    </executions>
</plugin>

JAXRS-ANALYZER uses three backends to create three different document formats. In the previous configuration the plaintext back end was used. After building the project, the following plaintext document will be built automatically:

REST resources of JAXRSAnalyzer:
1.0-SNAPSHOT

GET resources/sample:
 Request:
  No body

 Response:
  Content-Type: text/plain
  Status Codes: 200
   Response Body: java.lang.String


POST resources/sample:
 Request:
  Content-Type: text/plain
  Request Body: java.lang.String

 Response:
  Content-Type: */*
  Status Codes: 200
   Response Body: java.lang.String


POST resources/sample/entity/cosumer:
 Request:
  Content-Type: application/json
  Request Body: com.sam.jaxrsanalyzer.Sam
   application/json: {"name":"string","family":"string"}

 Response:
  Content-Type: */*
  Status Codes: 200
   Response Body: java.lang.String


GET resources/sample/entity/preview:
 Request:
  No body

 Response:
  Content-Type: application/json
  Status Codes: 200
   Response Body: com.sam.jaxrsanalyzer.Sam (application/json): 
{"name":"string","family":"string"}

This plain text document contains all the methods, paths, requests, responses, status codes and content types with no specific format.

To create a more structured document, the asciidoc and swagger backends could be used. Using asciidoc as the back end, the following asciidoc document will be created:

= REST resources of JAXRSAnalyzer
1.0-SNAPSHOT

== `GET resources/sample`

=== Request
_No body_ + 

=== Response
*Content-Type*: `text/plain`

==== `200 OK`
*Response Body*: (`java.lang.String`) + 

== `POST resources/sample`

=== Request
*Content-Type*: `text/plain` + 
*Request Body*: (`java.lang.String`) + 

=== Response
*Content-Type*: `\*/*`

==== `200 OK`
*Response Body*: (`java.lang.String`) + 

== `POST resources/sample/entity/cosumer`

=== Request
*Content-Type*: `application/json` + 
*Request Body*: (`com.sam.jaxrsanalyzer.Sam`) + 
`application/json`: `{"name":"string","family":"string"}` + 

=== Response
*Content-Type*: `\*/*`

==== `200 OK`
*Response Body*: (`java.lang.String`) + 

== `GET resources/sample/entity/preview`

=== Request
_No body_ + 

=== Response
*Content-Type*: `application/json`

==== `200 OK`
*Response Body*: (`com.sam.jaxrsanalyzer.Sam`) + 
`application/json`: `{"name":"string","family":"string"}` + 

The editors that parse asciidoc documents processe this rest-resources.adoc document and produce a graphical API documentation such as bellow:

The last back-end is swagger. Swagger is a tool that creates powerful REST API representation. By setting the back end to swagger, the analyzer generates a swagger document as follows:

{
    "swagger": "2.0",
    "info": {
        "version": "1.0-SNAPSHOT",
        "title": "JAXRSAnalyzer"
    },
    "host": "example.com",
    "basePath": "/resources",
    "schemes": ["http"],
    "paths": {
        "/sample": {
            "get": {
                "consumes": [],
                "produces": ["text/plain"],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "headers": {},
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            },
            "post": {
                "consumes": ["text/plain"],
                "produces": [],
                "parameters": [{
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }],
                "responses": {
                    "200": {
                        "description": "OK",
                        "headers": {},
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/sample/entity/cosumer": {
            "post": {
                "consumes": ["application/json"],
                "produces": [],
                "parameters": [{
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/Sam"
                        }
                    }],
                "responses": {
                    "200": {
                        "description": "OK",
                        "headers": {},
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/sample/entity/preview": {
            "get": {
                "consumes": [],
                "produces": ["application/json"],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "headers": {},
                        "schema": {
                            "$ref": "#/definitions/Sam"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Sam": {
            "properties": {
                "name": {
                    "type": "string"
                },
                "family": {
                    "type": "string"
                }
            }
        }
    }
}

The http://editor.swagger.io/ could be used to generate rich API documentation from the swagger.json document in hand. For instance the following API documentation has been created from the above swagger.json file by the swagger editor:

In swagger each path could be opened and tested individually in a user friendly manner.

To use JAXRS-ANALYZER as a standalone tool, analyzer jar file can be downloaded and be used to generate documentation from project files. JAXRS-ANALYZER documentation contains the steps and instructions on how to use analyzer as a standalone tool.

A tool such as JAXRS-ANALYZER helps programmers and development teams to create rich and precise REST API documentation automatically. Having a precise and up to date, API document increases development team’s productivity. JAXRS-ANALYZER analyses bytecode to generate API documentations. By the same token, there is no need to include any additional annotations or libraries to the projects. This means the code remains intact and existing projects could get benefits from this tool without any additional coding.

I begin to consider using such tools in my upcoming projects. Creating API documentation using such tools couldn’t be easier.