- Published on
Power-up your OpenAPI Spec in 13 steps
During my work on Superface Integration Designer, I used numerous OpenAPI Specification (OAS) files describing the APIs of some well known service providers. The quality of these specifications varies heavily, and if you decide to use them as input for some tool, you can end up with poor results. The poor quality of OAS files was frustrating for me, so I decided to write down the most common issues I ran into. The list is primarily focused on OpenAPI Specification, but most of the suggestions are applicable to other specification formats, and also touch upon API design.
Let's assume that you write an API specification. Why should you think about automated processing of your API specification? Because you will benefit from it in the long run. There is a growing number of tools that use OpenAPI Specification as input, and allow you to do things like validation, SDK code generation, API mocking, automated security checks, and more. If you build APIs, take a look at them. It could change the way you look at the role of API specification in your development process.
There is a common misconception that people create API specification for other people to read. Specification writers can then take shortcuts. Shortcuts lead to lower quality of API specification which, in the end, results in subpar output of tools processing your API specification.
Let’s look at the most common errors that complicate OAS documents use.
Play safe with versions
Use well established versions of OpenAPI Specification which are supported by automated processing tools. By using an established OAS version, you give your users a larger variety of tools compatible with your specification.
As of September 2022, the majority of tools supports OAS version 3.0, but not every tool supports OAS 3.1 or 2.0. When in doubt, check the list of tools.
Keep your API simple
This one is more connected to API design, but I consider this significant enough to be mentioned. When designing your API, keep in mind that you need to be able to describe it with OAS. So think twice before using non-standard security schemes or obscure request/response types.
For example, in one of the OAS documents we tested an endpoint that accepted either a string or an object with properties, and returned the same type based on the request contents. This kind of relationship between the request and the response is not possible to describe in OpenAPI Specification. The tool processing this specification has no way to connect the request schema with the appropriate response schema.
Describe everything, but keep it short
OAS document doesn't replace documentation, but complements it. It's a reference where each entity should be sufficiently documented, but shouldn't contain marketing language or information that isn’t directly needed to use the API. Tutorials, guides, and use cases belong to dedicated documents.
Provide a sandbox server
In the OpenAPI Specification, servers represents an array of objects with information on how to connect to different instances of the API. These can be, for example, production and staging servers. If all endpoints in your API require authorization, provide a sandbox service which operates on dummy data. This allows a user to quickly try out your API in their project.
Specify security
Define all security schemes and connect each endpoint to the correct scheme. Every scheme should describe how to obtain the key or authorize (or link to the documentation). Many OAS documents define multiple global security schemes, but don’t specify which endpoint uses which security scheme.
Keep the naming consistent
Use names that are descriptive and clear, avoid mixing different naming conventions (like camelCase, snake_case, and kebab-case). Avoid property names or enums starting with non-alphabetic characters (like numbers or dashes) as these can lead to issues during automated processing.
schema:
type: object
# DO NOT DO THIS:
properties:
accountName:
type: string
account_id:
type: string
account-description:
type: string
3h:
type: number
sort:
type: string
enum:
- -start_at
- +start_at
Enumerate all property types
When it comes to defining the data schema and property types, be as precise as possible. Don’t forget to cover whether an endpoint accepts multiple types, for example string and null. This information is crucial for the quality of the generated output. This is the most common problem I have encountered. When you generate an SDK from such an incorrectly described OAS document, the client code doesn't expect the value to be nullable, which will cause errors.
schema:
type: object
properties:
foo:
# Works in OAS 3.1
# foo can be string or null
type: ['string', 'null']
bar:
# Works in OAS 3.0
# bar can be string or null
type: string
nullable: true
Mark required properties
Make sure to correctly mark required properties. Ignoring the required property is another common mistake which affects validation and mocking tools.
schema:
type: object
properties:
foo:
type: string
# bar can be undefined
bar:
type: string
required: ['foo']
Don't forget errors
List all the error responses with correct status codes and response bodies, provide example errors, follow HTTP status code definitions. OpenAPI Specification allows multiple ways to define error response. You can use the default response, or wildcard response 4xx as described in the Specification. Error responses are vital when you are using the specification with a tool for mocking responses.
Add examples
You should provide a valid example for each parameter. These examples are useful for API mocking and SDK generation tools, as they can be used as mock values.
schema:
type: object
properties:
temp:
type: number
description: 'Temperature in kelvin'
example: 293.25 # <-- example value
description:
type: string
description: 'Weather condition within the group'
example: 'broken clouds' # <-- example value
country:
type: string
description: 'Country code (GB, JP etc.)'
examples:
- AU # <-- first example value
- CZ # <-- second example value
Define default values
For optional properties, make sure to specify a default value if there is one. Similar to examples, this is useful for tools and documentation purposes.
schema:
type: string
enum: [json, xml, html]
default: 'json' # <-- default value
Detail property format
In addition to type, you can also specify the format of the value, for example int32, date-time and password. You can also specify a regular expression. The full list of possible values can be found in the JSON schema specification. This is useful both for validation and mocking tools.
id:
type: integer
description: City ID
format: int32 # <--
example: 2172797
Use a linter
You can automate most of these checks by using an OpenAPI Specification linter. There are many linters out there, although most of them just validate OAS documents with a prepared JSON Schema. Our OpenAPI Linter takes a different approach, it uses the Spectral linter with a custom set of rules. These rules were designed to validate OAS documents intended for use with automatic processing tools.
In the list above, I highlighted parts of the specifications that are often neglected, but play an important role in automatic processing tools. Focus on these parts, so your specification is useful both for users and automatic processing tools. With a well-written API specification, users can automatically generate client code for your API, mock an entire server, and much more. These possibilities can give you a head start on your competitors. So remember, treat your OpenAPI Specification as code, not just as a structured document for humans.
Resources
Here is a list of articles that can be helpful when working on API specification:
Articles about design-first vs. code-first approach: