Overview

This guide documents the process for creating OpenAPI documentation for Grails-based FOLIO modules (e.g. Agreements, Licenses, Serials Management, Open Access) that can be automatically added to the FOLIO API documentation (listed at https://dev.folio.org/reference/api/endpoints/ ).

The workflow described here uses Redocly to create structured, multi-file OpenAPI specifications that can be validated, previewed, and built into a final YAML file.

Redocly is both a commercial service and a toolkit for documenting APIs using OpenAPI. This documentation is about using the freely available toolkit, not the service. Using Redocly allows the API to be defined using files in a directory structure (making it easy to re-use definitions of common components such as parameters that apply to multiple endpoints), supports validation of the definition, and will build a single distributable yaml file which contains the full definition compiled from the files in the repository. There is a Redocly OpenAPI extension available for Visual Studio Code allowing live validation of the schema as you build it, as well as command line tools (node based) to validate and build definitions (see the Redocly starter repository README)

The APIs are defined using the OpenAPI specification. The specification allows for extremely detailed documentation for APIs, but we can pick and choose the key elements for us. In the Serials documentation, I chose to document in detail:

• Paths (endpoints)

• Parameters

  • This includes common parameters from the K-Int Web Toolkit at a top level, but I did not go as far as documenting every property that can be used in a filter or match etc.

• Success responses

  • I did also document common error responses but in very little detail

• Content schemas (the JSON passed to/from the API)

  • This is where the bulk of the work lies!

The redocly approach allows you to define elements inline or via references to other files. Generally I’ve used references for paths, parameters and components . Where there is opportunity to re-use any definitions these can be done via references. Any decisions here are about the efficiency of writing the documentation - the final distributable definition file built by Redocly expands all the references into a single file.

High-Level Process

1. Set Up Your Working Environment

• Clone the Redocly OpenAPI starter repository

• Install dependencies (npm install)

• Update the /openapi/openapi.yaml file to have the basic information for a FOLIO API

2. Discover the Module's API Endpoints

• Use the ModuleDescriptor to find the endpoints exposed to OKAPI/FOLIO API gateway

• For each endpoint, add a path and ref to the openapi.yaml

3. Document the HTTP operations, parameters and responses for each path

• For each path you have documented, create a yaml file that corresponds to the ref for the path in the openapi.yaml

• To document the API, for each path we should list the operations (GET, PUT, POST, DELETE, etc.) supported by the endpoint, the parameters supported by the operation, and what responses can be received (at minimum the “success” response)

  • When defining parameters and the schema used by responses, at this point add only a reference to a file (which doesn’t have to exist yet) in the ../components/parameters ../components/schema directories

• See this example of a path definition with some suggested common and best practices

4. Document path parameters

• Once all the paths are documented, using the redocly npm test or using the Visual Studio integrated validation, you can identify what parameters need to be documented

• Each parameter should be documented in a file under ../components/parameters using the filename from the path definitions

• See this example of a parameter definition with some suggested common and best practices

5. Document Schemas (i.e. the structures of the request payloads and responses)

• Once all the paths and parameters are documented, using the redocly npm test or using the Visual Studio integrated validation, you can identify the top level schemas that need to be documented (i.e. those that are directly referenced in the paths or parameters

• You may identify additional schemas that are required as you document schemas (in situations where there is a schema that is part of another schema object, but not directly used by a path or parameter)

• Each schema should be documented in a file under ../components/schemas using the filename from the path and parameter definition

• See this documentation on how to document schemas (this is the most involved part of the process)

• See this example of a schema definition with some suggested common and best practices

5. Validate and build

• Validate the OpenAPI specification (npm test)

• Use Redocly tools to preview the documentation (npm start)

• Build the final bundled YAML file (npm run build)

6. Integrate with the Official Module Repository

• Copy the built OpenAPI YAML to the appropriate location in the official FOLIO module repository

• Follow the module's conventions for API documentation location (see Serials as an example)

• This will then be picked up by automated system operations process to add to the FOLIO API documentation e.g. https://s3.amazonaws.com/foliodocs/api/mod-serials-management/s/serials-management.html

Key Resources

FOLIO Module Repositories

• mod-serials-management

• mod-agreements

• mod-licenses

• mod-oa

Example Documentation Projects

• Serials Mangement

  • Serials Management API Documentation (Redocly based repo)

  • Serials Management OpenAPI definition (mod-serials-management repo)

• Agreements API Documentation (PoC) (outdated but potentially useful starting point)

Tools and Documentation

• Redocly Documentation

• Redocly OpenAPI Starter

• Bienenvolk Bruno collection

Redocly repository file structure

Your Redocly project will have this structure: