Documentation

Sapi-nt can automatically generate documentation for your API. This document explains how to configure documentation and details all the available features.

Configuration

The first step in supporting the API documentation is enabling the documentation endpoints. This can be done in two ways, namely using the application config file or creating a custom Spring controller Kotlin class.

Application Properties

To enable documentation controller via application properties set the sapi-nt.web.controller.doc.enabled property to true. This will enable the default documentation controller containing all the supported documentation endpoints listed here. The endpoints will be served on the /doc context path by default. Optionally you can configure a different context path for the documentation controller by setting it in the sapi-nt.web.controller.doc.path property. The source code of the default documentation controller can be found here.

Custom Controller

If you do not want all endpoints implemented by default, or you want them implemented differently you can create a custom Spring controller Kotlin class that extends the DocumentationBaseController. Your new class will have to be annotated with a @Controller Spring annotation and each method should correspond to one endpoint where @RequestMapping annotation is used to specify the endpoint path. You can use the default documentation controller as a reference. Table below documents functions inherited from the DocumentationBaseController.

Name	Parameters	Description
`respondWithDocumentation`	Path to the pebble template used to render the page	Responds with the API Documentation
`respondWithValidator`	None	Responds with the API Documentation validator
`respondWithModelDoc`	Path to the pebble template used to render the page	Responds with the Model Documentation
`respondWithOpenApiSpecJson`	Path to the pebble template used to render the page	Responds with the OpenAPI Specification

NOTE: All pebble templates should be stored in src/main/resources/templates and the provided path parameter should be relative to that directory.

Documentation Endpoints

API Documentation

The API documentation is generated using the DocTool class which aggregates all the API features in a user friendly navigable HTML document.

Requirements/Configuration

Follow these steps to configure the API documentation:

Create a directory under src/main/resources which is going to hold all documentation related files.
Inside the application properties file (i.e. application.yaml) specify the path to the documentation directory under sapi-nt.config.docSpecPath. This path should be prefixed with classpath: and be relative to the src/main/resources directory. If you have generated the project using the sapi-nt-archetype you will have the value set to classpath:documentation.
Inside the documentation directory create a configuration file named documentation.yaml and any external HTML files that you want the DocTool to load into the specified sections.
For each of your API endpoints you want to document, specify the properties related to documentation in their configuration files.

Custom Documentation Template

If you are not happy with the default documentation template you can override it with a custom one. To do that, create a template called documentation.peb inside the pebble templates folder of your application. The template will have access to a variable called doc, which is an instance of the DocTool class. Inject the generated documentation sections into your template by calling the methods on doc, making sure that the HTML is not escaped. That can be achieved using a raw pebble filter, for example {{ doc.renderApiDetail() | raw }}.

Endpoints

By default, two endpoints are supported. One serving the documentation in HTML format, i.e. /${doc-path}/reference, and one validating the documentation.yaml and serving results in plain text format, i.e. /${doc-path}/validate. The validation endpoint is useful when populating documentation.yaml as it will point out any endpoints that do not have a class or a group defined as well as any invalid example links.

Model Documentation

See here for the full documentation of the model documentation feature.

OpenAPI Specification

The OpenAPI Specification(OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. sapi-nt has capabilities of serving the OAS in both json format as well as an interactive HTML page generated by the swagger UI.

Requirements/Configuration

Similarly to the model documentation, OAS is automatically configured as long as there is an endpoint serving it. If you are creating a custom documentation controller rather than using the default documentation controller set up using the application properties then you just need to define two request mappings, one for each media type, namely text/html and application/json as seen here.

Endpoints

A single endpoint, i.e. /${doc-path}/oas, serves the OAS as both json and HTML using the Swagger UI.