Skip to content

Home

Development

IDEs

API Explorer

Gloop REST API documentation

Martini automatically generates an HTML API documentation page for your Gloop REST APIs. You can access this page using the URL {http|https}://{host}:{port}/doc/{api-namespace}. The documentation page is generated using Gloop templates, and can be customized.

Example API documentation

Consider the examples package's HelloYou Gloop REST API. This API's complete namespace is apis.restApi.HelloYou. If Martini is deployed at localhost:8080, then this API's documentation can be accessed at localhost:8080/doc/apis.restApi.HelloYou. This URL is also displayed in the Gloop REST API editor's Documentation tab, so you can view it while working on your API.

Use proper tags

Your REST API operations must have proper tags set for them to appear in the documentation.

Customising API documentation

Martini allows you to customise the Gloop template responsible for generating the API documentation of your Gloop REST APIs. To do this, you only need to define certain package properties.

You must restart your package to apply API documentation template changes

To apply your API documentation customisations, you have to restart your Martini package after changing its package properties file.

These are the package properties you can use to customise the API documentation Gloop template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Path/URL to the top navigation bar image
api.doc.navbar.image=
# Path/URL to the sidebar image
api.doc.sidebar.image=
# Path/URL to the CSS file which will be used instead of the default main CSS file
api.doc.css=
# Path/URL to extra CSS files, where you can add your own styles
api.doc.external-css=
# Namespace of the Gloop template which will override the default Gloop template used to render the navigation bar.
api.doc.navbar.template=

Default Gloop template

You can either use an HTTP URL, or a relative path for the following properties:

1
2
3
4
api.doc.navbar.image=
api.doc.sidebar.image=
api.doc.css=
api.doc.external-css

Relative paths are ideal if you want to use local images or CSS files. To use a relative path, your resource must be stored underneath the package web directory and its respective package property must be set to a path following this pattern: /<package-name>/<file-path-relative-to-web-directory>1.

Consider the following Martini package:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
petstore
├── code
│   └── io.swagger.petstore
│       ├── ...
│       └── Petstore.api
└── web
    └── static 
        ├── style
        │   ├── main.css
        │   └── extra.css
        ├── petstore.png
        └── swagger.png

To add extra CSS styling to API documentation pages, and replace the navigation bar image, and sidebar image (in order) of this package, we supply the following package properties:

1
2
3
api.doc.external-css=/petstore/static/style/extra.css
api.doc.navbar.image=/petstore/static/swagger.png
api.doc.sidebar.image=/petstore/static/petstore.png

Default API documentation page

Customised API documentation page

Custom Gloop template

If you're going to use a custom Gloop template, you must set the api.doc.navbar.template property to the namespace of your template file. You can copy the namespace of your template by right clicking it from the Navigator, and then selecting "Copy Namespace".

1
api.doc.navbar.template=io.swagger.petstore.DocumentationNavBar

The template overrides the navigation bar only

The custom Gloop template is used to customise the top part of API documentation pages. The content is generated from Gloop REST API definitions, and can be custom styled through CSS.

To use images and/or CSS files in your template, you must import them as Gloop template resources. Providing a custom Gloop template will make Martini ignore the api.doc.navbar.image property. Other api.doc.* properties are used as usual for the template.


  1. This is the same path pattern used when importing local web resources in Gloop templates