REST API Documentation Using JAXRS-ANALYZER

DZone's Guide to

REST API Documentation Using JAXRS-ANALYZER

Here;s a look at REST API documentation with the JAXRS-Analyzer. API documents are by default technical catalogs, and developers must have instructions fir requesting service from platforms or systems.

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:

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:

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.