Power-up your OpenAPI Spec in 13 steps
Tags: api, webdev, openapi, tooling
Published: 2022-09-29 15:10:49


During my work on [Superface Integration Designer](https://superface.ai/blog/integration-designer-announcement), 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][openapi.tools] 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][openapi.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.

```yaml
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.

```yaml
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.

```yaml
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](https://swagger.io/specification/#responses-object). 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.

```yaml
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.

```yaml
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](https://json-schema.org/understanding-json-schema/reference/generic.html). This is useful both for validation and mocking tools.

```yaml
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](https://github.com/superfaceai/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.

{% embed https://github.com/superfaceai/openapi-linter %}

---

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:

- [Specification of OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [JSON Schema Specification](https://json-schema.org/specification.html)

Articles about design-first vs. code-first approach:

- [Stoplight: Design first](https://blog.stoplight.io/api-first-api-design-first-or-code-first-which-should-you-choose)
- [APIs You Won't Hate: Design First](https://apisyouwonthate.com/blog/api-design-first-vs-code-first)
- [Swagger: Design First](https://swagger.io/blog/api-design/design-first-or-code-first-api-development/)

[openapi.tools]: https://openapi.tools