API governance needs good tooling, and rules that fit – so today’s post covers both.

Fun fact: I work at Redocly and had used the tool for years, but recently realised that I have a post about a different tool in the archives of my blog, but no Redocly post. So here’s the Lorna-recommended version of OpenAPI linting with Redocly CLI.

Linting won’t make your API secure or necessarily delightful, but it can pick out some key aspects and check them programmatically. Typically you’d include linting in your CI (Continuous Integration) setup so that you get the checks run all the way through the API development lifecycle. It’s also key to be able to run the tools locally for immediate checks when you’re working on your API description.

You can read the docs for Redocly CLI for the details but in summary: an open source CLI tool that helps with every aspect of an OpenAPI description, including configurable linting. Install the tool and lint your API description with the following command:

redocly lint openapi.yaml

If you get a lot of output, DON’T PANIC.

All the linting tools come with default or “recommended” rulesets, but they aren’t a perfect fit for every situation so they’re not always a great default. My biggest advice around API linting is that every team needs to use a custom ruleset to meet its own needs and context. The recommended is a good starting point when you’re totally new to these tools, but they’re a one-size-fits-nobody solution, and you’ll want to adapt.

Redocly CLI is configured by redocly.yaml, and again, the docs are excellent (yes, I am biased!), but to get you quickly started with a reduced but still relevant ruleset, try this configuration as a starting point:

rules:
spec: error
no-identical-paths: warn
no-server-trailing-slash: warn
no-unresolved-refs: error
operation-operationId-unique: error
operation-operationId-url-safe: warn
spec-components-invalid-map-name: warn
no-invalid-media-type-examples: warn
no-example-value-and-externalValue: error
no-unused-components: warn
operation-operationId: warn

You still need to edit your own configuration and add/remove things that make sense for your use case, but especially if you’re retro-fitting API governance to an existing API or APIs, the recommended ruleset can be a bit much!

Beyond the provided rules

In addition to a customised ruleset, I’d expect most teams to need some configurable rules and even some transformation steps of their own. I’ve written before about Overlays, and Redocly CLI also has some nice custom plugin functionality that makes it easy to add resusable rules, sorting operations, or a variety of other features.

Here’s an example for checking that the API description has an info.version field that uses semantic versioning format:

rule/version-is-semver:
subject:
type: Info
property: version
assertions:
pattern: /^[0-9]+\.[0-9]/
severity: error
message: info.version must use semantic versioning.

Creating these custom rules is a great way to pick up on the naming rules and other conventions that you want to have done right for every change to every API.

For more rule and plugin examples, Redocly CLI has a cookbook where you can find lots of examples, and share your secrets with others too – so if you have rules that work for you, I’d love to see them!