Introduction

For server-side projects that utilise RAML or OpenAPI (OAS), use the tool api-doc to generate API documentation from its API description files and schema and examples.

The tool is available for use during FOLIO Continuous Integration builds, and also for local use prior to commit. Currently RAML 1.0 and OAS 3.0 or OAS 3.1 are handled.

Usage

For use during FOLIO CI builds, refer to the GitHub Workflows configuration section below. Note that the project should also use “api-lint” which utilises the same configuration for the properties apiTypes, apiDirectories, etc.)

For local use, clone the “folio-tools” repository parallel to clones of back-end project repositories, and use its api-doc facility. Refer to that document for local installation instructions.

Python

The Python script will search the configured directories to find relevant API description files, and will process each file to generate the API documentation representation.

Where the main options are:

• -t,--types – The type of API description files to search for. Required. Space-separated list. One or more of: RAML OAS
• -d,--directories – The list of directories to be searched. Required. Space-separated list.
• -e,--excludes – List of additional sub-directories and/or files (just filenames, not paths) to be excluded (so that the tool will only discover top-level root API description files). Optional. Space-separated list. By default it excludes certain well-known directories (such as raml-util examples headers parameters). Use the option --loglevel debug to report what is being excluded.

Don’t quote a space-separated list. Correct: -e examples headers. Wrong: -e "examples headers". Wrong: "-e examples headers".

See help for the full list (including the default output directory):

python3 ../folio-tools/api-doc/api_doc.py --help

Example for RAML:

cd $GH_FOLIO/mod-courses
python3 ../folio-tools/api-doc/api_doc.py \
  -t RAML \
  -d ramls

Example for OAS:

cd $GH_FOLIO/mod-eusage-reports
python3 ../folio-tools/api-doc/api_doc.py \
  -t OAS \
  -d src/main/resources/openapi \
  -e examples headers

Example for both RAML and OpenAPI (OAS), i.e. when preparing for transition:

cd $GH_FOLIO/mod-foo
python3 ../folio-tools/api-doc/api_doc.py \
  -t RAML OAS \
  -d ramls src/main/resources/oas

GitHub Workflows

All relevant back-end repositories are now configured to use GitHub Workflows for the API-related tasks. See the .github/workflows directory and the “Actions” UI tab.

The configuration properties are further described as comments in each workflow file.

Note the workflows only operate when there is a file change commit in their API descriptions directory. Be sure to add to the “on: paths” sections of the workflow file.

NOTE: For back-end modules, also add the path to ModuleDescriptor, because the api-doc facility interprets the MD to match the endpoints to interfaces. Therefore the Workflow run will be triggered when the MD is modified. (The edge-modules do not provide interfaces in their MD, so no need.)

NOTE: When preparing the pull-request for initial setup, make a follow-up commit to one of the API description files. This is because the Actions runs are only triggered when those files are changed.

For a new project repository, follow the implementations for a similar repository. (All were done via FOLIO-3678). Some example PRs (but if copied, then do ensure that Workflow actions are updated - see note below):

• mod-courses – RAML.
• mod-settings – OAS.
• mod-notes – OAS.
• mod-calendar – OAS. This one also needs to “exclude” some sub-directories.

Occasionally verify that your workflow files are up-to-date (e.g. for the versions of dependent “actions”). Compare with the default files at folio-org/.github/workflow-templates.

Jenkinsfile