As explained in the Primer for back-end development the RAML Module Builder (RMB) framework can be utilised to ease development. One of its abilities is to generate Java classes from the RAML and Schema.

FOLIO uses RAML version 1.0

RAML and schema files are also utilised in other ways, for example the Okapi Web service and Tenant interface, the mod-graphql, and by other non-RMB modules.

The RMB README section entitled Design the RAML files provides some RMB-specific guidance, as well as general assistance.

The mod-graphql Autogeneration of GraphQL schemas and resolvers document explains the RAML and Schema files.

The RMB README has an example and commentary.

As explained there, use the shared git submodule at ramls/raml-util and follow the ideal directory structure. See notes about thereafter updating submodules.

When using RMB, it is important to further emphasise some items. Pay attention to the “$ref” used to reference and link the JSON Schema. For RAML-0.8 and RMB prior to v20, there must be at least two endpoints, and all schema that are used must be declared in the RAML file.

Use “api-lint” to assess API descriptions, schema, and examples. A script is provided, to find files and run it. That script can be run locally, and is also utilised by the continuous-integration.

Describe schema and properties.

Use “api-doc” to generate documentation from the API descriptions, schema, and examples. That script can be run locally, and is also utilised by the continuous-integration to build the FOLIO API documentation and the associated list of endpoints.

Investigate the other RAML-using server-side modules.

Reference API documentation is automatically generated by the continuous integration, for modules that are managed with the FOLIO CI.