Managing API Documentation Content

This topic provides information relating to managing your API documentation on the Akana API Platform.

It includes:

Working with the Documentation Table of Contents

If you add, modify, or delete API documentation files, you will probably also want to update the documentation table of contents (TOC). In the user interface, the documentation table of contents appears on the left navigation bar, and provides clickable links into the documentation. The TOC is controlled by a JSON file that resides in the main documentation folder. You can edit the JSON file to control how the documentation TOC looks.

The JSON filename includes the name of the API version; for example, toc.apiversion23609.acmepaymentscorp.JSON. This allows you to control the table of contents for each version, even though the documentation for all versions shares the same folder structure.

If you only have one index page for the documentation, the contents of the JSON file might look something like this:

{
  "toc":[
    "index.htm"
  ],
  "sequence":[
    "index.htm",
    "toc.apiversion23609.acmepaymentscorp.json"
  ],
  "displayNames":{
  }
}

You can modify the JSON file as needed to control:

  • The files that appear on the TOC
  • Their display names
  • The sequence in which they appear

The example below adds two additional files to the TOC:

{
  "toc":[
    "api_reference.htm",
    "index.htm",
    "troubleshooting.htm"
  ],
  "sequence":[
    "index.htm",
    "api_reference.htm",
    "troubleshooting.htm"
    "toc.apiversion17171.acmepaymentscorp.json",
  ],
  "displayNames":{
    "index.htm":"API Doc Homepage",
    "api_reference.htm":"API Reference",
    "troubleshooting.htm":"Troubleshooting"
  }
}

Just upload the modified file in the same way that you would upload any other documentation file, using the POST /content/{path} (with multipart/form-data content-type) operation.

Supporting Multiple Languages

The platform allows you to set up your API documentation to support multiple languages, should you wish to do so.

If the documentation is available in multiple languages and is set up correctly for multi-language support, the user can request API documentation in a specific language. If a language is not specified, and multiple languages are available, the platform detects the user's locale setting and returns content in that language, if it is available. If the locale setting is null, the platform returns content in whatever language the content owner specified as the default language.

Managing API Documentation with Swagger

The platform includes a utility, Swagger, that generates user documentation based on the API definitions that you provide as part of the API setup.

Swagger allows you to write additional documentation, such as descriptions of the API, operations, parameters, messages, and so forth. This documentation can be saved as a resource in the metadata store which can be used to get and read from templates using the Content service, specifically the GET /{contentpath} operation.

At runtime, the documentation displayed for your users combines the automatically-generated content along with any written content you have provided, in a seamless display. This allows you to easily provide basic documentation and add to it when you are able.

The API service includes these Swagger-related operations: