Readers familiar with OpenAPI can skip this section. |
OpenAPI is a standard for describing REST APIs in a language-independent form. The OpenAPI Specification is maintained by the OpenAPI Initiative, an industry body with members from companies that develop and use REST APIs, including Google, Microsoft and many others. OpenAPI was previously known as Swagger.
What it Does
An OpenAPI document is a text file (YAML or JSON) that describes the operations that are available in a REST API. The document contains detailed information about parameters and types required by the API, and the HTTP requests and responses used by each operation. This document is the authoritative description of the API, which can be used by developers that need to work with the API.
Examples
The OpenAPI YAML excerpt below shows how a typical REST operation may be specified.
This operation uses a HTTP GET request, with the path /pet/{petId}
, where {petId}
is an integer, e.g. /pet/1234
.
The response will contain JSON or XML content that follows the referenced schema (in another
part of the document, not shown here).
paths:
'/pet/{petId}':
get:
tags:
- pet
summary: Find pet by ID
description: Returns a single pet
operationId: getPetById
parameters:
- name: petId
in: path
description: ID of pet to return
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/json:
schema:
$ref: '#/components/schemas/Pet'
An interactive example can be seen at https://editor.swagger.io/. This is a web application that lets users edit their API and see the changes immediately in the generated documentation.
What this enables
A standard, unambiguous way to describe REST APIs is useful as a form of documentation for the humans that use the API. But the real benefit is the automation from tooling that understands these documents. Tools that support OpenAPI can use these documents to generate clients, servers, tests or documentation for the API.
The OpenAPI document is usually sufficient to completely generate a client implementation.
For example, most client generators will turn the above operation into a getPetById(long)
method
that applications can call, without knowing about the underlying HTTP requests and responses.
This is very powerful and means that REST APIs can be adopted easily when they are specified in OpenAPI.
The server implementation of an API cannot be completely generated as there will be application logic needed to query or update databases or other components, but the skeleton of a server implementation can be generated, with stubs for the developer to fill in the application logic.
The open source openapi-generator tool is commonly used for generating code from OpenAPI documents. It supports many programming languages and frameworks, and can be extended to generate custom code. It forms the basis of the Rhino REST API Framework toolchain for generating SLEE client and server code.