Validating OpenAPI Schemas

As a part of a larger effort to design a complex authentication system, the developers asked for an OpenAPI (formerly Swagger) specification for one RESTful API of the system in question. Although it is pretty straightforward to write both in YAML and JSON, we needed validation and it turned out that there is a validation tool that is both easy to install and use!

The OpenAPI specification version 3.2.0 is what we used to describe a bunch of RESTful API endpoints. Some GET requests for service discovery, some POST requests for session creation, some targets for 3rd party services to redirect to - the usual mixture of interfaces you would expect.

When we finished writing and made sure it reflects our design document, we needed a validator. Given the confidentiality of the project, we could NOT use an online validator and therefore we looked for those that can be run locally.

And there is the openapi-spec-validator written in Python.

Given our previous experience with heterogenous Python environments like testing and documentation we knew we want to do everything in a venv - that is a Python Virtual Environment. As a refresher of our memory, setting it up is pretty straightforward:

python3 -m venv openapi
. ./openapi/bin/activate

According to the documentation, the installation should be as easy as:

pip install openapi-spec-validator

And it turns out, it is. No problems with neither the package nor its dependencies. The usage is also simple:

$ openapi-spec-validator my-schema.yaml
my-schema.yaml: OK

Well, it did not show this result when we run it for the first time, of course. However it helped us with fixing meta-data and schema issues in a few places without any hiccups. The easiest one being ensuring the proper OpenAPI version - you can guess it was the latest one.

Hope you liked this little side quest into a different domain-specific language then it is typical for us and be sure to tune in next time!