Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src/main
README.md
pom.xml

README.md

Holon platform examples: Swagger V3 API documentation with JAX-RS

This is one of the Holon Platform example projects.

This example shows how to setup a Swagger/OpenAPI version 3 API documentation endpoint using the Holon platform JAX-RS module, with PropertyBox data type support.

Topics

This example addresses the following topics:

  • Use the @ApiPropertySetModel annotation to declare a property set as a named Swagger model bound to PropertyBox type API operations requests and responses
  • Use the Holon JAX-RS Swagger integrations for Spring Boot to automatically setup and configure a Swagger API listing endpoint.

Example structure

This JAX-RS server implements a simple RESTful API to provide the Product data model entity management, backed by an in-memory store, using Jersey as JAX-RS implementation and Tomcat as servlet container.

The server API uses the PropertyBox class as data container and JSON as data exchange format, leveraging on the Holon platform JSON module Jackson JAX-RS support.

The ProductEndpoint class represents the API endpoint and provides operations to get a product, get all products and create/update/delete a product. It is declared as a singleton Spring bean through the @Component annotation and it is auto-configured as JAX-RS resource by the Holon platform auto configuration facilities.

A JDBC Datastore is auto-configured and used for product entity data manipulation and persistence.

Some Swagger annotations are used to provide API operations description (@Operation) and response details (@ApiResponses).

The @ApiPropertySetModel annotation

The @ApiPropertySetModel annotation is used to create a Swagger model definition, with a given name, from a Holon PropertySet declaration.

The @PropertySetRef annotation is used to declare the PropertySet which is bound to a PropertyBox request or response object type.

To improve code organization, consistency and readability, the ProductModel annotation is defined, which is in turn annotated with @ApiPropertySetModel (using the Product model name) and @PropertySetRef (declaring the Product class as the source of the product PropertySet).

The ProductModel annotation is used in API operations to qualify a PropertySet type request body or response type.

This way, a Product model definition will be declared in the Swagger API definitions and used as a reference for each PropertySet type request or response element.

Swagger V3 API listing endpoint configuration

The holon-jaxrs-swagger-v3 artifact of the Holon platform JAX-RS module, declared as dependency in project's pom, provides Spring Boot integration to auto-configure the Swagger API listing endpoint, using the holon.swagger.* configuration properties (see application.yml).

This way, a JAX-RS Swagger API listing endpoint to generate and provide the Swagger API documentation is automatically configured and listing at the api-docs path by default:

http://localhost:8080/api-docs

The endpoint provides the Swagger definitions in JSON by default, but the type parameter can be used to specify the response format: json or yaml.

http://localhost:8080/api-docs?type=yaml

To change the path of the API listing endpoint, the holon.swagger.path property can be used. So, for example, setting holon.swagger.path=docs will result in the following Swagger API listing URL:

http://localhost:8080/docs?type=yaml

See the Swagger JAX-RS integration documentation for details and other configuration options.

Documentation

The complete Holon Platform reference guide is available here.

For the specific documentation about the modules and the components used in this example see:

System requirements

The Holon Platform is built using Java 8, so you need a JRE/JDK version 8 or above to build and run this example projects.

License

All the Holon Platform modules and examples are Open Source software released under the Apache 2.0 license.

Holon Platform Examples

See Holon Platform Examples for the examples directory.