If you work with APIs at all, either creating or consuming them, you’ve probably heard of something called the OpenAPI Specification (or its former name, Swagger). However, you may be fuzzy on the details. Don’t worry! By the end of this post you won’t be.

What is this OpenAPI thing, anyway?

The OpenAPI Specification (OAS) is a way to describe your API so that all its resources and operations can be read by both humans and machines. Your OAS document can be in JSON or YAML. Once you have one, you can leverage all sorts of OAS-compliant tools to add really helpful functionality, including:

  • interactive API documentation
  • SDK generation
  • testing and debugging

Also, describing your API with an OAS document makes it more likely that your API and your documentation remain in sync, reducing developer and user frustration!

The OpenAPI Specification is an open-source project of the OpenAPI Initiative, a vendor-neutral group that is one of the Linux Foundation’s Collaborative Projects. Members of the initative include 3Scale, Apigee, Capital One, Google, Intuit, Microsoft, PayPal, and, of course, IBM!

You can find the full OpenAPI Specification here.

Open API Spec / Open API Initiative

How Do I Create An OAS definition?

A typical OAS document looks something like this:

swagger: '2.0'
info:
  version: 1.0.0
  title: My Awesome API
  description: An Awesome API 
paths:
  /awesome:
    get:
      operationId: getAwesome
      description: Returns guaranteed awesome
      parameters: 
        name: flavor
        in: query
        required: false
        type: string              
      responses:
        200:
          description: Successful response 

You can write one by hand if you want, or you can use a number of open-source tools and editors to create one. (Check out Swagger Editor and this tutorial series for more tips.)

If you are creating your API with LoopBack, you can export your OAS definition easily.

I Have an OAS Document … Now What?

Once you have your OAS document, your options for exploring, testing, and debugging your API expand. Here’s a run-down of some of these options:

In short, anything you need to do with your API, OpenAPI Spec makes easier, faster, or clearer.

What’s Next?

OAI Specification v3 has been announced. If you’re interested in contributing, you can find more information here.