For server-side projects that utilise RAML or OpenAPI (OAS), use the tool
api-lint to assess the API description files and schema and examples.
Each discovered API description file is provided to the nodejs script.
That utilises the AML Modeling Framework AMF, specifically the
amf-client-js library, to parse and validate the definition.
Note: Some modules might find new violations being reported. Refer to Interpretation of messages below.
For use during FOLIO CI builds, refer to the GitHub Workflows configuration section below. Note that the project should also use “api-doc” which utilises the same configuration for the properties apiTypes, apiDirectories, etc.)
The Python script will search the configured directories to find relevant API description files, and will then call the node script to process each file.
-t,--types– The type of API description files to search for. Required. Space-separated list. One or more of:
-d,--directories– The list of directories to be searched. Required. Space-separated list.
-e,--excludes– List of additional sub-directories and/or files 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). Use the option
--loglevel debugto report what is being excluded.
-w,--warnings– Cause “warnings” to fail the workflow, in the absence of “violations”. Optional. By default, if there are no “violations”, then the workflow is successful and so any “warnings” would not be displayed.
See help for the full list:
python3 ../folio-tools/api-lint/api_lint.py --help
Example for RAML:
cd $GH_FOLIO/mod-courses python3 ../folio-tools/api-lint/api_lint.py \ -t RAML \ -d ramls
Example for OAS:
cd $GH_FOLIO/mod-eusage-reports python3 ../folio-tools/api-lint/api_lint.py \ -t OAS \ -d src/main/resources/openapi \ -e headers
Example for both RAML and OpenAPI (OAS), i.e. when preparing for transition:
cd $GH_FOLIO/mod-foo python3 ../folio-tools/api-lint/api_lint.py \ -t RAML OAS \ -d ramls src/main/resources/oas
The node script can also be used stand-alone to process a single file.
See usage notes with:
node amf.js --help
All relevant back-end repositories are now configured to use GitHub Workflows for the API-related tasks.
.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.
- 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.
At GitHub, detected issues are listed at the “Actions” tab. For any branch or pull-request build, follow the “details” link via the coloured checkmark (or orange dot while building).
Ensure valid JSON Schema
While api-lint can detect many issues with broken JSON Schema, it is advisable to ensure that the schema are valid locally before pushing changes to CI. Otherwise the messages from api-lint can be confusing.
There are many schema validation tools. One such is z-schema:
for f in schema/*.json; do z-schema --pedanticCheck $f; done
Of course it is also advisable to follow on to verify the API descriptions locally with api-lint before pushing to continuous integration.
Interpretation of messages
When errors are encountered, then a summary of conformance “Violations” and “Warnings” is presented at the top, followed by detail about each. The detail includes the location of the relevant file and the line number of the problem.
Note that if there are only warnings but no violations, then nothing is presented.
--warnings option described above.