sajad torkamani

In a nutshell

The OpenAPI specification is a human and machine-readable specification (typically in YAML or JSON format) that describes HTTP APIs.

Describing an API in a standard format unlocks several capabilities:

  • You can use the spec document to generate interactive documentation (e.g., using a tool like Swagger UI).
  • Developers can read the spec to understand how to use the API (e.g., what endpoints are available, what data is expected for each endpoint, what status code is returned, etc.).
  • You can generate server stubs and client SDKs from spec (e.g., using a tool like Swagger CodeGen).

The spec schema

The full schema reference can be found here, but what follows are some of the most important fields.

openapi

Specifies the version number of the spec (e.g., 3.0.1).

info

Provides metadata about the API. For example:

"info": {
  "title": "My Lovely API",
  "description": "Some description",
  "version": "0.0.0"
},

paths

Describes the paths and operations (e.g., GET, POST) for the API.

servers

An array of Server Objects, which provide connectivity information to the API’s consumers.

components

Contains various schemas for the document. For example:

"components": {
  "schemas": { // usually contains you entities / models },
  "responses": {},
  "parameters": {},
  "examples": {},
  "requestBodies": {},
  "headers": {},
  "securitySchemes": {}
},

Sources

Tagged: Misc