This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Swagger Integration

Swagger is used for the REST-API documentation. It can be requested on the following URL: https://<INSTALLATION>/nice2/swagger.

Swagger works with the OpenAPI Specification. In order to work correctly all REST resources must be described by Swagger Annotations out of which the OpenAPI specification is generated.

Swagger is integrated in the nice2-rest-doc module.

Swagger is integrated as follows

1. Swagger-UI as Static Resource

Swagger UI is a tool to generate a single page which visualizes the REST resources. To generate the page download the latest version of Swagger UI, open a terminal and go to the downloaded folder. Run the following commands:

  • npm install

  • npm build

The generated page now should be inside the dist folder.

Warning

The commands could be different in newer versions. Check the scripts page for more information.

The generated page is copied to PATH/TO/NICE2/rest/doc/module/resources/webapp/swagger.

The static paths are configured in the class RestDocStaticResourcesConfiguration.

Edit the index.html and replace the value of the url property with "/nice2/openapi". This url tells Swagger where to fetch the OpenAPI Specification.

Additionally set all links to the generated JS and CSS files correctly. For example replace href="./swagger-ui.css" with href="swagger/swagger-ui.css"

2. NiceOpenApiServlet

The NiceOpenApiServlet extends the OpenApiServlet which produces the OpenAPI Specification for the Swagger-UI page.

In the NiceOpenApiServlet the following is configured:

  • All REST resources

  • Some information like the company and contact data

  • The authentication mechanism (so that authenticated requests can be executed)

The serlvet can be requested under <INSTALLATION>/nice2/openapi.

3. Describe REST Resources with Swagger Annotations

To describe the REST resources Swagger Annotations are used. The NiceOpenApiServlet converts these to the OpenAPI Specification.

Check the Swagger Annotation docs to see how resources can be described.

Example:

@Path("/entities/{name}")
public interface EntitiesResource extends RestResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @JacksonFeatures(serializationEnable = {SerializationFeature.INDENT_OUTPUT})
    @Operation(
        summary = "Load entities",
        description = "Load entities of a given model with paging and optional sorting",
        tags = "entities"
    )
    CollectionBean getEntities(
        @PathParam("name") @Parameter(description = "name of the entity model to load") String modelName,
        @QueryParam("_offset") @Parameter(description = "offset from first result for paging") String offset,
        @QueryParam("_limit") @Parameter(description = "max amount of entities to load") String limit,
        @QueryParam("_sort") @Parameter(description = "comma separated string of fields to sort by") String sort
    );
}