Setting Default Values for API Documentation Information

You can set default values for API documentation information by adding marked-up text to the Documentation Text of your REST class, the methods of that class, and any component classes needed by the API.

When generating a specification, whether using the OpenAPI Generation Wizard or the JadeOpenAPIGenerator RootSchema class, the documentation text is parsed for the REST API class, the paths (methods) of that class, the servers, and any component classes and their properties.

Tags must be of the following form.

<tag-name>value</tag-name>

In some cases, tags may need to be nested inside other tags. Any other text in the documentation text is ignored; for example, the documentation text in the following image is for a REST API class.

For this documentation text, the text that is not marked up at the beginning and end is ignored, but the text inside the tags provides the default values for the API Description and Servers sheets of the OpenAPI Generation Wizard.

The following tags can be used to provide default values for OpenAPI descriptive elements. Where a tag is nested inside another tag, this is represented in the following table as tag/sub-tag.

REST API Class Information

The following table lists the tags and sub-tags that you can use to set default values.

Tag	Description
info	Sub-tags for the descriptive elements relating to information about the API itself.
info/title	Title of the API.
info/description	Purpose of the API.
info/license	Optionally contains sub-tags for the name and URL of the license of the API, if applicable.
info/license/name	Name of the license applied to the API; for example, GNU GENERAL PUBLIC LICENSE.
info/license/url	URL to the license used for the API. It must be in the format of a URL.
externalDocs	Optionally contains sub-tags for the description and URL of target external documentation, if applicable.
externalDocs/description	Short description of the target documentation.
externalDocs/url	URL for the target documentation. It must be in the format of a URL
servers	Contains sub-tags for the descriptive elements relating to information about the servers from which the API is accessible.
servers/server	Contains sub-tags for the URL and description for a specific server from which the API is accessible.
servers/server/url	URL to a server from which the API is accessible.
servers/server/description	Description of a server from which the API is accessible.

REST API Paths (Methods)

The following table lists the tags that you can use to set path (method) default values.

Tag	Description
summary	Summary of the intent of the path.
description	Description of the path, which can include parameters and a return type.

Component Classes

The following table lists the tags that you can use to set component class default values.

Tag	Description
description	Description of the class.
example	Example JSON representation of an object of the class.

Component Properties

The following table lists the tag that you can use to set the component property default value.

Tag	Description
description	Description of the property.

2020.0.02 and higher