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.
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 |
|
Default Gloop template
You can either use an HTTP URL, or a relative path for the following properties:
1 2 3 4 |
|
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 |
|
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 |
|
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 |
|
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.
-
This is the same path pattern used when importing local web resources in Gloop templates. ↩