Global TechHubHome
Introduction
OpenAPI Specification (formerly
Swagger Specification) is an API description format for REST APIs. An OpenAPI
file allows you to describe your entire API, including:
v Available endpoints (/users) and operations on each endpoint
(GET /users, POST /users)
v Operation parameters Input and output for each operation
v Authentication methods
v Contact information, license, terms of use and other
information.
API specifications can be written in
YAML or JSON. The format is easy to learn and readable to both humans and
machines.
In this article, I am going to explain
basic Structure of OpenAPI Specification.
Overview
You can write OpenAPI definitions in
YAML or JSON. In this guide, we use only YAML examples but JSON works equally
well. All keyword names are case-sensitive. A sample OpenAPI 3.0 definition
written in YAML looks like:
Metadata
Every OpenAPI specification starts
with the openapi keyword mentioning the version of the specification format.
This version defines the overall structure of an API specification – what you
can document and how you document it. Earlier, the format field included two
components (for example, 2.0). Since version 3, OpenAPI is using semantic
versioning with three components. The latest version is 3.0.0:
The info section contains API information: title, description
(optional), version:
title is your API
name. description is extended information about your API. It can be multiline
and supports the CommonMark dialect of Markdown for rich text representation.
HTML is supported to the extent provided by CommonMark (see HTML Blocks in
CommonMark 0.27 Specification). version is an arbitrary string that specifies
the version of your API (do not confuse it with file revision or the openapi
version). You can use semantic versioning like major.minor.patch, or an arbitrary
string like 1.0-beta or 2017-07-25. info also supports other keywords for
contact information, license, terms of service, and other details. Reference:
Info Object.
Servers
The servers section specifies the API
server and base URL. You can define one or several servers, such as production
and sandbox.
All API paths are relative to the
server URL. In the example above, /customers means https://apim-services.mybluemix.net/banka/v1/customers
, depending on the server used.
Paths
The paths section defines individual
endpoints (paths) in your API, and the HTTP methods (operations) supported by
these endpoints. For example, GET /customers can be described as:
An operation definition includes
parameters, request body (if any), possible response status codes (such as 200
OK or 503 Internal Server Error) and response contents.
Parameters
Operations can have parameters passed
via URL path (/user/{userId}), query string (/users?role=admin), headers
(X-CustomHeader: Value) or cookies (Cookie: debug=0). You can define the
parameter data types, format, whether they are required or optional, and other
details:
Request Body
If an operation sends a request body,
use the requestBody keyword to describe the body content and media type.
Responses
For each operation, you can define
possible status codes, such as 200 OK or 404 Not Found, and the response body
schema. Schemas can be defined inline or referenced via $ref. You can also
provide example responses for different content types:
Note that the response HTTP status
codes must be enclosed in quotes: "200" (OpenAPI 2.0 did not require
this)
Input and Output Models
The global components/schemas section
lets you define common data structures used in your API. They can be referenced
via $ref whenever a schema is required – in parameters, request bodies, and
response bodies. For example, this JSON object or can be represented as:
Authentication
The securitySchemes and security
keywords are used to describe the authentication methods used in your API.
Supported authentication methods are:
ü HTTP authentication: Basic, Bearer, and so on.
ü API key as a header or query parameter or in cookies
ü OAuth 2
ü OpenID Connect Discovery
Conclusion
The OpenAPI Specification (OAS)
defines a standard, language-agnostic interface to RESTful APIs which allows
both humans and computers to discover and understand the capabilities of the
service without access to source code, documentation, or through network
traffic inspection. When properly defined, a consumer can understand and
interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be
used by documentation generation tools to display the API, code generation
tools to generate servers and clients in various programming languages, testing
tools, and many other use cases.
The full OpenAPI 3.0 Specification is
available on GitHub:
Download
S. No
|
File Name
|
Size
|
Download
|
1
|
OpenAPI
Specification Basic Structure.pdf
|
1.0 MB
|
Comments
Post a Comment