Providing Swagger tag descriptions

RESTful endpoints (both Support for RESTful invocation of Business Task and Business Entity Methods and RESTful services ) support custom tags via a tags attribute value. Descriptions and other detail for those tags can be provided in a file.

File structure

The file contains JSON data and includes the tag name and a description of the tag, and optionally information about an external documentation URL. The JSON objects have the following structure.

{
  "<tag name>": { 
      "description": "<tag description>",    // required
      "url": "<url for external documentation of the tag>",    // optional
      "urlDescription": "<url text>"    // optional
  }
}

For example,

{
  "pets": { 
      "description": "Everything about your Pets",
      "url": "http://docs.my-api.com/pet-operations.htm",
      "urlDescription": "Click here for pet info"      
  },
  "store": {
      "description": "Access to Petstore orders",
      "url": "http://docs.my-api.com/store-orders.htm",
      "urlDescription": "Click here for store info"
  }
}

Tag file configuration

The location of the file is configured in the .restapplicationsettings file , in the swagger settings. A new tags property holds the relative or absolute path of the file containing the tag descriptions and other information.

"swagger": {
   "tags": "swaggertags.json"
}