Tech Blog

How We Build our Documentation Using OpenAPI

Earlier this year, we announced our support for OpenAPI in the Alma APIs. This support powers our API Console, enables you to leverage the growing number of tools which support Open API, and can be used as a starting point to build client SDKs.

In this blog post, we’ll look at how we use our OpenAPI support to keep our API documentation on the Developer Network up-to-date.

Our implementation is based on Apache JAX-RS for the REST API logic and XSD schemas to define the objects. The artifacts that we maintain in our code base are Java classes and XSD files. We use JAXB to convert the XSD schemas into POJOs, and we generate WADL files from the JAX-RS classes. We use XSL transform to generate the HTML documentation you see on the Developer Network from the WADL files and from the XSD schemas.

This “code-first” approach ensures that the documentation is never out-of-synch from the actual API implementation as it’s generated directly from the code.

Now that we have added support for OpenAPI, we’ve created additional XSL scripts which convert our WADL files into JSON & YAML specification files and XSDs to JSON schema files. Those files are provided as input to the API console and are used to create the XML and JSON examples you see in the documentation.

Samples for the input to the Create Fine API generated using the Swagger Inflector tool

This latest addition means that you get the most updated and detailed API documentation possible, all of which is intended to enable you to get the information you need to focus on your business logic and build your apps on the Alma platform.

The image below illustrates how the files flow as we build our documentation for each monthly release.

Hope you enjoyed this peek behind the scenes!

Leave a Reply