To reduce repetition, the OpenAPI YAML file is generated using the m4 macro processor. The YAML file should therefore not be edited directly: instead the template file should be edited and the YAML regenerated using make.
To simplify the build process, we check in the generated file as well as the source: some operating systems may not come with m4 or have a simple way to install it.
The Makefile provides four targets that can be used to check the correctness of the OpenAPI specification and its associated JSON Schemas:
schemalintchecks the JSON schemas using AJVexamplelintchecks that the example records conform to the appropriate schemasapilintchecks the API file using FOLIO's api-lintlintruns all threee of these checks
The AJV command-lint client can be installed using npm -g install ajv-cli.
FOLIO's api-lint is a little more complicated to install:
$ git clone https://github.com/folio-org/folio-tools
$ cd folio-tools/api-lint
$ yarn install
$ pip3 install -r requirements.txt
// ... and symbolically link folio-tools/api-lint/api_lint.py somewhere on the path
The Makefile provides a doc target that can be used to generate human-readable documentation from the OpenAPI specification and its associated JSON Schemas, using FOLIO's api-doc. The documentation will be generated in the doc subdirectory.
FOLIO's api-doc is installed the same way was api-lint, but from folio-tools/api-doc.
The API documentation is generated by continuous-integration during the merge to mainline branch and published.