Model Documentation

The model documentation is generated by the Model-doc library. The Sapi-nt application supplies its default model to the library to produce a HTML fragment, which is served as part of a web page.

You can use Spring configuration properties to configure the features of the underlying model-doc library. See the Model-doc documentation for details.

Endpoints

The model documentation endpoint is /${doc-path}/model, where doc-path is the configured documentation context path, or doc by default. It serves text/html content.

Grouping

You can define groupings of related classes in your model to enhance the structure of the generated documentation. Groupings also allow you to provide additional contextual information for each group, including UML diagrams, if they are enabled.

See the model-doc documentation for details of how to define a grouping.

In order to use a grouping in sapi-nt, you must specify the location of the grouping definition file (YAML) by setting the sapi-nt.doc.model.grouping.path configuration property. This property uses the Spring resource location syntax, and can be the location of a file on the local file system (file:) or a classpath resource (classpath:).

Diagrams

You can include UML diagrams as part of your model documentation by enabling the diagram features of model-doc (documented here), and configuring sapi-nt to provide the diagram files over HTTP.

The basic configuration properties for model-doc are:

This can be achieved either by serving them as static resources, or by having sapi-nt generate each diagram upon request.

Static Resources

To serve diagrams as static resources, you must first generate the diagrams by running the model-doc standalone application. Make sure that you generate the correct diagrams for the model and class grouping (if any) that you intend to use in your sapi-nt application.

Then, set up a resource mapping from /doc/diagram to the location of your generated diagrams, using the Spring resource location syntax. This can be the location of a directory on the local file system (file:), or a classpath resource (classpath:).

Example

# application.yaml
sapi-nt:
  config:
    resourceAliases:
      - contextPath: "/doc/diagram"
        aliases: [ "classpath:/diagram/" ]

Dynamic Resources

To have sapi-nt generate diagrams dynamically, you must enable the relevant controller by setting the sapi-nt.web.controller.diagram.enabled configuration property to true.

If you wish to maintain a cache of previously generated diagrams on the local file system, you can enable the caching feature of model-doc by setting model-doc.diagram.cache to true.

Note that in order to generate diagrams, a suitable graph visualisation engine must be available in the application’s environment.