Power-up your OpenAPI Spec in 13 steps

Jakub Vacek — Thu, 29 Sep 2022 15:10:49 +0000

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.

superfaceai / openapi-linter

Is your OpenAPI Spec ready for SDK generators?

OpenAPI Linter

Is your OpenAPI Spec ready for SDK generators?

OpenAPI Linter is a CLI and a Node.js library to validate OpenAPI specification It is based on Spectral by Stoplight with OpenAPI rules with additional rules. The goal of Linter is to check whether the spec contains enough information to generate high quality, well documented SDK We use OpenAPI Linter in Superface Integration Designer, but any client code generator benefits from well written OpenAPI specs.

Setup

Install from npm globally:

npm i -g @superfaceai/openapi-linter

Now you can use the linter with commands openapi-linter or oal.

Alternatively you can use the linter without installation with npx:

npx @superfaceai/openapi-linter lint <file or URL>

CLI commands

openapi-linter lint SPECIFICATIONPATH

`openapi-linter lint SPECIFICATIONPATH`

Lints OpenAPI specification using three different parsers/validators.

USAGE
  $ openapi-linter lint [SPECIFICATIONPATH] [-f yaml|json] [-e error|warning|any]
ARGUMENTS
  SPECIFICATIONPATH  Path or URL to specification file

FLAGS
  -e, --throwOn=<option>     [default:

…

View on GitHub

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:

Forem: Jakub Vacek

Power-up your OpenAPI Spec in 13 steps

Play safe with versions

Keep your API simple

Describe everything, but keep it short

Provide a sandbox server

Specify security

Keep the naming consistent

Enumerate all property types

Mark required properties

Don't forget errors

Add examples

Define default values

Detail property format

Use a linter

superfaceai / openapi-linter

Is your OpenAPI Spec ready for SDK generators?

OpenAPI Linter

Setup

CLI commands

openapi-linter lint SPECIFICATIONPATH

Resources

`openapi-linter lint SPECIFICATIONPATH`