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.
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.
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
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.
Here is a list of articles that can be helpful when working on API specification:
Articles about design-first vs. code-first approach:
Single SDK for ATS, CRM, SMS and e‑mail APIs
Superface is a single API client for hundreds of APIs. Providing fast, stable, direct API integrations that do not compromise on speed or privacy.