The on-line API documentation is automatically generated by the continuous integration system when changes are merged to master. The Jenkinsfile for each back-end module declares when the module is ready to publish, via its publishAPI parameter.

The configuration metadata for all raml-related back-end modules is manually managed at the api.yml file. This configuration is utilised by both this publishAPI and the runLintRamlCop CI jobs, and by this website.

NOTE: This configuration is gradually being phased out, as projects start to use doApiLint and doApiDoc (see Jenkinsfile).

Please ensure that the module’s RAML or OAS API descriptions can be processed without error. The guide Assess API descriptions, schema, and examples will assist. The quality of the generated documentation depends on its input. Some issues can cause the CI system to fail. It is available to run locally by cloning folio-tools.

Add or update configuration

Main api.yml

Each RAML-related repository has an entry in the main api.yml file. (See also the supporting Groups below.)

When your new project repository has its initial “ramls” directory established, there will be no configuration for it. That is okay, as the CI jobs will attempt to use the default structure and will automatically discover the files to be processed.

The configuration is also needed for this website to produce the table in its API documentation.

To add a new entry for a new module, copy the “default” entry shown at the top of that file. Follow the configuration of other similar modules.

Prior to commit, ensure proper YAML format. For example: yq '.' _data/api.yml

The configuration entry can be tested by locally running the runLintRamlCop CI job (i.e. folio-tools/lint-raml).

Send a pull request for the api.yml file (and the Groups file if needed).

Occasionally the set of files to be published may need to be updated. As explained in the “files” section below, this is a manual task for the time being.

Groups apigroup.yml

The apigroup.yml file assists the website to provide the navigation Table-of-Contents.

Add new modules to the relevant group.

The order of entries in this file is the order of display at the API documentation.

Configuration file format

This section explains the format of the main api.yml configuration file. (The format of the other apigroup.yml file is self-explanatory.)

label

Usually an entry has one set of documents, so the label is null. Otherwise use this to add a text label to distinguish each set.

directory

The filesystem path of the directory holding the RAML files. Relative to the top-level of the repository. Usually this will be “ramls”.

files

The basename of the set of files to be processed. The order is the order of display in the table.

RAML files that are not listed here will still be automatically discovered and processed by the CI jobs. However they will only be shown in the table if they are configured here, as the website documentation system needs to know.

ramlutil

The filesystem path of the directory holding the shared “raml-util” git submodule. Relative to the top-level of the repository. Usually this will be “ramls/raml-util”.

excludes

The system will search for RAML files in and below the specific directory. Use this field to specify directories that must not be traversed. The default exclusions are ["raml-util", "rtypes", "traits", "node_modules"] and these additional excludes are appended.

version1

Set version1 to true if this is known to be RAML-1.0 version. Default is false, or this property can be omitted to denote that. This enables the API docs table to exclude the “view-2” column as explained in the usage notes.

schemasDirectory

For some non-standard layouts, the Describe schema and properties component of the lint-raml-cop CI job needs to be provided this pathname to the JSON schemas. Otherwise it searches under the “ramls” directory, which might cause it to discover additional files.

multiple

To assist mod-graphql to handle interfaceType=multiple rather than reading ModuleDescriptor. Set multiple to true if this module provides the “multiple” interface. Default is false, or this property can be omitted to denote that.

rmb

This property denotes that the module is based on the RAML Module Builder.

The default is true, or this property can be omitted to denote that.

Setting this to false enables the lint-raml-cop CI job to avoid some RMB-specific extra tests.