Holon platform examples: Swagger V3 API documentation with JAX-RS
This is one of the Holon Platform example projects.
This example addresses the following topics:
- Use the
@ApiPropertySetModelannotation to declare a property set as a named Swagger model bound to
PropertyBoxtype 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.
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 (
@ApiPropertySetModel annotation is used to create a Swagger model definition, with a given name, from a Holon
@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
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
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:
The endpoint provides the Swagger definitions in JSON by default, but the
type parameter can be used to specify the response format:
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:
See the Swagger JAX-RS integration documentation for details and other configuration options.
The complete Holon Platform reference guide is available here.
For the specific documentation about the modules and the components used in this example see:
- Holon platform JAX-RS module reference documentation
- Holon platform JAX-RS Swagger integration
- Documentation about the Property model
- Documentation about the Datastore API
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.
Holon Platform Examples
See Holon Platform Examples for the examples directory.