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
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:
-
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 create SDKs easily with swagger-codegen. If you are using IBM’s Bluemix, this is already available to you as a plugin!
-
You can generate test code.
-
You are able to confirm that your backend and your description are in sync.
-
You can check for breaking changes in your API, or integrate with any number of commercial tools, including uploading your OAS document to API Connect.
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.