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.
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
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:
You can add an interactive API sandbox explorer with swagger-ui (you might already be familiar with swagger-ui, as it’s used in LoopBack).
You can generate test code.
You are able to confirm that your backend and your description are in sync.
In short, anything you need to do with your API, OpenAPI Spec makes easier, faster, or clearer.