Spectral can help you find out if your OpenAPI is valid and matches your organization’s style guide or even if your API has security holes, but with this latest ruleset, Spectral is helping your API documentation be the best it can be.
OpenAPI has a whole load of functionality that most of us don’t entirely remember, but with the Documentation Ruleset, you can have Spectral automatically point out when you or the team are missing low-hanging fruit for making API documentation excellent.
What makes excellent API Documentation?
This is a huge topic in general, and there’s a lot more to good API documentation than just
API Reference Documentation.
Focusing on the API Reference Documentation, there is a huge world of difference between API reference docs rendered from a really minimal OpenAPI description and one that’s leveraging OpenAPI well. It’s pretty understandable that an API might have a minimal OpenAPI description at first when it’s being designed, but as it matures and makes it to production, you’d hope that it’s had some extra effort put in, maybe by the API Developers, maybe by the API Product Manager, maybe by Technical Writers.
Whoever is in charge of making the documentation great quality, the goal of the documentation Ruleset is to point out what can be done to make sure they are great and automatically flag anything less than great.
Descriptive Descriptions
Documentation tools use descriptions to provide more context to users of the API who are
not as familiar with the concepts as the API designers are. These descriptions could be on
the operation, schema, parameters, tags, or even in the info block at the top describing the
API itself.
The goal of all these descriptions is to explain not just what but why and sometimes how. For example, I think we can all probably guess that GET /events are getting a list of events,
so this description could be considered minimal: '/events': get: operationId: get-events summary: Get Events description: 'Get a list of all the events'
What would be more useful is pointing out that this endpoint actually has a default state,
which is to only show future events.
'/events':
get:
operationId: get-events
summary: Get Events
description: 'Get a list of events, which defaults to only showing
upcoming events. To include past events include the `?past=true` parameter.'
That’s better! Not much more room for a surprise there. You can explain all sorts of awkward things in a description.
paths: '/upload': post: summary: Upload a Tree description: 'Internal endpoint for iOS app only, to upload a tree fromthe field.' operationId: post-upload x-internal: true
“Oh, but I am building a web app for this API, but it’s saying iOS only?” It probably means you and the folks maintaining that API need to have a chat because they’re not expecting you clearly, and there might be a few other surprises lurking.
The docs-descriptions rule in the Documentation Ruleset will not only make sure that the description field exists, but will ensure its more than 20 characters long, ends with a full stop, and starts with a capital letter, all of which will make sure it doesn’t look super weird in documentation tools.
Schema or Examples
Most good API reference documentation will show a sample request and response, and the
docs-parameters-examples-or-schema and docs-media-types-examples-or-schema
rules are there to make sure that documentation tools have provided enough information
for these to be constructed.
One way your OpenAPI-based docs can generate a sample request is via the schema
keyword, which is used to dynamically produce a sample by inferring data types, potential
values, etc. This can get a long way, especially if request/response properties have their
own examples, or use other validations like default, enum, format, etc., but for more
complex dynamic payloads, this can start to fall short.
Another approach is to provide them statically by using some sort of example or examples
keyword (depending on the version).
Some folks may just want to provide a schema; some may want to provide just an example. This rule will make sure you do at least one. Ideally, you’ll do both; then Spectral can let you know that your examples are valid against your schemas.
Tags Are Pretty Handy
Tags are used by some documentation tools to group logic to avoid forcing end-users to scroll through hundreds of URLs to find the endpoints they’re looking for. This might manifest in nested navigation or searchable terms, but however, tags are leveraged by the documentation tool in question, so having them is more useful than not. There are a few rules for tags in this ruleset.
Firstly, docs-tags is suggesting you add tags at the top level, so in JSON Path, that would be $.tags. This is where tags are defined, and it’s a handy place to pop a description to explain what the grouping is all about.
Then docs-operation-tags is the other side of the coin, basically saying that now you’ve defined tags, then it makes sense to reference them in operations. Without referencing the previously defined tags, then, the tags aren’t going to do anything.
Finally, there’s docs-tags-alphabetical, which is helping avoid the situation where tags are defined in some arbitrary order assuming they will be alphabetized, but the documentation tool is showing them in the literal order. Basically, some tools might show the tags in B, A, and C order, which is not always what is expected. This may be fairly opinionated but generally is useful more often than not. If you want to disable this rule or any other rule, then Overrides are your friend.
Summary
Sadly you can’t just bung any old OpenAPI description into a documentation tool like Stoplight Elements, ReDoc, or Swagger UI and expect the best results, but the Documentation Ruleset can make it a lot easier to find the right OpenAPI functionality to leverage so you’re not fumbling around in the dark.
This ruleset is open-source on GitHub or available on the Stoplight Platform. However you use it, we would love to get some feedback. You can open issues or send a pull request if you have experience with creating Spectral rulesets.
