Page Comparison

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.

...

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

1. Marking parts of the schema as 'undocumented' so they won't appear in the reference docs

2. Providing example values for schema objects, which are included in the documentation to show how it can be used.

Location of metadata.json files

...

server/mod/perform/webapi/metadata.json				# will be included when building metadata for all schemas.
server/mod/perform/webapi/external/metadata.json	# will only be included when building metadata for external schema.
lib/webapi/metadata.json							# core metadata.json file for all schemas.
lib/webapi/ajax/metadata.json						# core metadata.json file for ajax schema only.
server/local/customplugin/webapi/metadata.json		# metadata.json file in a third party plugin.

Building of single metadata.json file

...

{
	"OBJECT": {
		"Mutation": {
			"fields": {
				"undocumented_mutation": {
					"documentation": {
						"undocumented": true
					}
				}
			}
		},
		"Query": {
			"fields": {
				"undocumented_query": {
					"documentation": {
						"undocumented": true
					}
				},
				"my_query": {
					"args": {
 						"undocumented_arg": {
							"documentation": { "undocumented": true }
						},
						"my_query_arg": {
							"documentation": { "example": "example_for_my_query_arg" }
						}
					}
				}
			}
		},
		"undocumented_object_type": {
			"documentation": {
				"undocumented": true
			}
		},
		"my_object_type": {
			"fields": {
				"my_object_type_field": {
					"documentation": {
						"example": "example_for_my_object_type_field"
					}
				}
			}
		}
	},
	"SCALAR": {
		"undocumented_scalar": {
			"documentation": {
				"undocumented": true
			}
		},
		"my_scalar": {
			"documentation": {
				"example": "example_for_my_scalar"
			}
		}
	},
	"INPUT_OBJECT": {
		"my_input": {
			"inputFields": {
				"undocumented_input_field": {
					"documentation": {
						"undocumented": true
					}
				},
				"my_input_field": {
					"documentation": {
						"example": "example_for_my_input_field"
					}
				}
			}
		}
	},
	"ENUM": {
		"my_enum": {
			"enumValues": {
				"undocumented_enum_value": {
					"documentation": {
						"undocumented": true
					}
				},
				"my_enum_value": {
					"documentation": {
						"example": "example_for_my_enum_value"
					}
				}
			}
		}
	},
	"INTERFACE": {
		"my_interface": {
			"fields": {
				"undocumented_interface_field": {
					"documentation": {
						"undocumented": true
					}
				},
				"my_interface_field": {
					"documentation": {
						"example": "example_for_my_interface_field"
					}
				}
			}
		}
	}
}

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.

...

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 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.

...

We also mediate the output to allow us to perform permission checks before displaying it, and to allow us to dynamically replace the https://YOUR-SITE-URL URL with the actual Totara site URL within the documentation.

...

In order to build the API documentation you will need:

• A working php command with access to the site's dataroot folder

• A working node command with access to the site's dataroot folder

In many cases, you may have a single environment that meets both of these requirements, however, our Docker setup used by many developers keeps PHP and node in separate containers, so it is also possible they won't be available at the same time.

...

The first step is to run a PHP build step, which completes the following tasks:

• Build the schema for each endpoint type and store it in a separate file (api/schema.{$endpoint_type}.graphqls) in the site's dataroot

• Build the metadata for each endpoint type and store it in a separate file (api/metadata.{$endpoint_type}.json) in the site's dataroot

• Build the site's component navigation structure (the name and title of all installed components) and store it in a file (api/nav.js) in the site's dataroot

The script is executed as follows (starting from the code root folder):

...