This is one of the Holon Platform example projects.
This example shows how to setup a Swagger specification version 2 API documentation endpoint using the Holon platform JAX-RS module, with PropertyBox data type support.
This example addresses the following topics:
- Use the
@ApiPropertySetModelannotation to declare a property set as a named Swagger model bound toPropertyBoxtype 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 (@ApiOperation) and response details (@ApiResponses).
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.
The holon-jaxrs-swagger-v2 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/api-docs
The endpoint provides the Swagger definitions in JSON format by default, but the type parameter can be used to specify the response format: json or yaml.
http://localhost:8080/api/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/api/docs?type=yaml
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.
All the Holon Platform modules and examples are Open Source software released under the Apache 2.0 license.
See Holon Platform Examples for the examples directory.