08.API Documentation - JohnyzHub/jax-rs GitHub Wiki

Restful web service provides standard and language-independent interface to the users to discover the capabilities of API without reading the source code.

WADL document contains all the global information related to the restful webservice such as relationship between the resources and the method metadata details. Jersey framework has built in support for generating WADL file for the jax-rs web service. To generate WADL file, simply access the rest url http://host:port/resource/context-root/application.wadl, generates the wadl file in xml format

Eg: http://localhost:8080/moviedirectory/rest/application.wadl

Most modern application servers are coming with the out-of-box support for OpenAPI specification. In order to generate openApi for any restful web service deployed to the application server payara simply access the url http://localhost:port/openapi, generates the open api documentation in yaml format.
Eg: http://localhost:8080/openapi

In the above two approaches we saw so far, though, provides the minimal documentation. Means, It takes some effort for a non-technical person to understand these documents due to the lack of detailed description.

Currently the most popular and widely used framework for documenting restful services is Swagger
Refer the resource class MovieDirectoryService to understand how the swagger annotations are used to document the resource. To generate the swagger documentation, simply access http://localhost:8080/moviedirectory/rest/swagger.json