Extending API documentation

Note that the in-product API documentation described on this page currently only applies to the external API. However, any schema comments will be available to GraphQL clients via introspection, so may be used to generate inline documentation and auto-complete hints in some clients.

When developing new services for Totara's GraphQL APIs, it is important to consider how your services will be documented, as this ensures that they can be easily used by other developers. This page outlines some technical considerations to keep in mind, including information on how to document API services, as well as the associated tooling for generating browsable documentation pages.

Authoring API reference documentation

Authoring guidelines for new documentation

For information on what to write in your API documentation, see our authoring guidelines.

Technical details on writing documentation

Schema comments

GraphQL has native support for exposing schema comments via introspection, meaning the comments on the schema files themselves can be extracted and converted into user reference documentation. This has the advantage that it keeps the explanation close to the schema it references, making it easier to keep up to date.

To document a schema item, include a string surrounded by three sets of double-quotes, either on a single line or across multiple lines like this:

""" This is a single line comment on the foo scalar """
scalar foo

"""
This is a multi-line comment on the `bar` scalar.

You can put as much information as you need in here:
* Markdown
* Is supported
* For basic
* Formatting
"""
scalar bar

Please note that basic markdown is supported, but don't use more complex formatting such as HTML or the special interpolation syntax provided by our documentation tool, as it may not be displayed correctly in all clients.

One additional feature we do support is that we'll automatically convert the string:

https://YOUR-SITE-URL

into the actual URL of the site, so you can use this string within your schema comments to create valid URLs within your site.

When commenting on a schema, it should be possible to put comments on all parts of the schema. In some cases you may need to break up arguments or fields over more lines to make space for the comments. For example:

""" Comment on 'car' type """
type car {
  """ Comment on 'colour' field """
  colour: String!
  """ Comment on 'top_speed' field """
  top_speed(
    """ Comment on top_speed 'format' argument """
    format: speed_options = KPH
  ): Int!
}


""" Comment on 'speed_options' enum """
enum speed_options {
  """ Comment on 'KPH' enum value """
  KPH
  """ Comment on 'MPH' enum value """ 
  MPH
}

extend type Query {
  """ Comment on 'get_cars' query """
  get_cars(
    """ Comment on 'limit' query argument """
    limit: Int = 10
  ): [car!]!
}

Note how the query return type doesn't have a comment - that is obtained from the comment on the type, rather than within the query definition.

metadata.json files

Unfortunately, the GraphQL specification does not provide a mechanism for documenting everything that we want to specify about our schema. To supplement the existing information, the documentation tool we are using to generate reference documentation (SpectaQL) supports providing additional metadata, which is used during the build process. See Building API reference documentation below for more details.

Currently the tool offers support for two additional features, by allowing you to specify a metadata.json file containing the extra information:

Marking parts of the schema as 'undocumented' so they won't appear in the reference docs
Providing example values for schema objects, which are included in the documentation to show how it can be used.

Location of metadata.json files

The tool requires a single file with all the metadata, however, Totara is an extensible system with the need for plugins to be able to extend core schema. To solve this, we support individual metadata.json files within each plugin, and our documentation build script provides support for merging individual files into a single output file, similar to how .graphqls schema files are combined to generate the overall schema.

Like .graphqls schema files and .graphql persisted query files, metadata.json files can be defined either for all schema (by putting in the webapi/ folder of a particular component) or for a specific endpoint type (by putting in a subfolder such as webapi/ajax/). Some example valid file locations include:

Currently, API documentation is only built for the external schema, so metadata.json files specific to other endpoints will not be used. In the future we may build reference documentation for other schema endpoints.

Building of single metadata.json file

As part of the documentation build script (see the section below), we merge all the individual metadata.json files for a specified endpoint type to generate a final file, which is used to build the reference documentation.

This is done by merging JSON keys recursively to create a new output JSON object that can be saved to a file. Components must avoid naming collisions to avoid generating an invalid output structure, however, collisions are not expected if individual components only provide metadata for their own schema definition, given the component-based namespacing used within our schema.

Structure of metadata.json files

The metadata file is in JSON format, and should be structured as follows (omit any sections that are not required):

See the SpectaQL documentation and example metadata.json file for more details.

Getting the structure of the metadata file so the data is taken into account can be tricky. Here are some tips to get it working:

Make sure your file is valid JSON, including double quoting all keys and correct use of commas (no missing or unwanted trailing commas). It can be useful to validate your JSON with your IDE or an online JSON validator to pick up any issues.
Be careful when copying and pasting sections - note that there are inconsistencies in key names (for example: "inputFields" for input types vs. "fields" for object types).
Ensure you put your references within the correct top-level category (for example input types go in "INPUT_OBJECT" but result types go in "OBJECT", and interfaces are separate too).
Note that queries and mutations go as a sub-type of the "OBJECT" key, and have a different structure to other types (OBJECT.Query.fields.query_name as opposed to OBJECT.type_name).
The examples above are all strings, but they can also be JSON objects themselves.
Note that to document a query you actually need to provide example data for its input and result types, not the query itself.

It can be helpful to start from the example structure above and modify it, rather than trying to generate it from scratch.

Markdown guides

SpectaQL also supports text-based documentation in the form of markdown files that can be displayed in a table of contents in the Introduction section. In Totara, those files are stored in the directory extensions/api_docs/spectaql/guides/, and should be saved with the .md file extension. They are included in the navigation via configuration in extensions/api_docs/spectaql/config.yml.

Other build configuration, including the Totara theme and navigation generation code, can be found in extensions/api_docs/spectaql/.

Building GraphQL API Documentation

Please see our guide for Building GraphQL Documentation below.

Public developer documentation