The elements of successful developer experience include a lot of context beyond the simple reference of what’s possible. Increasingly, OpenAPI—a specification that defines REST APIs—is used to create a machine-readable version of an API’s endpoints and other components. Since these documents aren’t meant for developers to read directly, it can be tempting to declare API definitions outside the realm of developer experience.

However, there are a number of ways OpenAPI documents help improve developer experience. Here are a few of the ways API descriptions help you:

• Generate developer documentation
• Share your API before you code
• Encourage a comprehensive reference
• Provide API documentation examples
• Enables additional tooling to help developers

Of course, since good developer experience includes nuance, there are certainly some things missing from OpenAPI. We’ll cover all of the above in the next few sections.

Updated Documentation is Table Stakes

Many developers familiar with OpenAPI (or its predecessor Swagger) think of API descriptions as synonymous with documentation. That’s likely because Swagger UI was the first popular tool to use the format. However, auto-generated documentation is only one way OpenAPI helps developer experience.

And at this point, updated documentation should be something developers demand and providers deliver.

Yet, plenty of API company docs trail behind API changes. With an OpenAPI document, you can publish a complete API reference (often with interactive functionality) every time the definition changes. Your developer documentation stays in sync with reality.

Provides a Place to Document Before Code

Developer experience begins well before someone arrives at your docs. No matter the audience of your API, understanding their needs before you build will provide a better experience. The OpenAPI specification gives you somewhere to capture the output from your earliest planning.

Many developers think in code. OpenAPI enables potential consumers of your API to get into code mode sooner. Your OpenAPI definition can generate documentation or even mock servers. When an API looks like the real thing, developers can poke at it to see if common use cases are possible.

It may seem obvious that your API should support the things developers want to accomplish. Yet, like up-to-date documentation, many APIs underperform in making common tasks easy. An OpenAPI document can enable better practices by thinking through what’s needed earlier in the process of building an API.

Encourages Complete API Descriptions

The presence of an OpenAPI document does not immediately mean APIs become more usable. As with most things, it’s the people who adopt and perform processes that lead to great developer experience. An OpenAPI definition can merely enable the right decisions and make them easier.

The description field in the OpenAPI spec is one of those ways to support a complete definition. These human-readable strings give you a chance to explain the concepts in your API at an endpoint and even data level.

     parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32

Of course, nothing is stopping an engineer from leaving the field blank or filling it with unhelpful descriptions. Some of these could be caught by OpenAPI tools like Spectral. In other cases, it’s a good opportunity for collaboration with a product manager or tech writer.

Enables Automated Tooling to Help Developers

In addition to tools mentioned above, there are many other ways to use OpenAPI descriptions. Because it’s machine-readable, you can generate resources for developers that improve their experience.

• SDKs or client libraries: It’s tough to keep these updated across multiple languages when you’re writing them by hand. I saw this first-hand working in developer relations. That’s one of the reasons I’m an advisor to APIMatic. The solution isn’t simple, but OpenAPI makes it possible.
• Mock API servers: Complete OpenAPI documents include response objects and every field’s type. That’s enough information to mock an API request/response cycle, which is helpful for a developer’s own testing or to get feedback as you build your API.
• Testing against a live API: skeptical developers can use your OpenAPI document to confirm it matches your published API. Accuracy ensures a better developer experience. You can perform this type of testing, sometimes called “contract testing,” yourself, as well.

There’s a whole community site dedicated to all the things you can do once you have your OpenAPI document.

What’s Missing from OpenAPI?

Despite the many ways that OpenAPI benefits developer experience, it doesn’t cover all the bases a developer will need.

Two major gaps we’ve noticed are:

• Getting started tutorials
• Codified use cases

These two are related. Each requires knowledge of what a developer wants to accomplish and provides a narrative for how it is done.

OpenAPI is an excellent foundation for developer experience. You can use it to provide up-to-date information and useful tools to help understand an API. But there’s no substitution for providing the human context in an authentic developer voice.

EveryDeveloper can help you augment your OpenAPI-generated tools with content to help developers be more successful.