OpenAPI Specification

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

External

Internal

Overview

OpenAPI Specification (OAS), formerly Swagger Specification, is an API description format and a specification standard for HTTP REST APIs. The specification for an API can be expressed in a single file, which provides the source of truth for the API, starting with the API design phase, then continuing with client and server code generation, documentation and testing. The specification format is programming language agnostic, it is machine-readable and it can be used to generate code in different languages. API specifications are typically written in YAML or JSON. The latest version at the time of this writing is OpenAPI 3.1.0.

The OpenAPI specification describes endpoints and operations for each endpoint, input and output parameters for each operation, authentication methods, contact information, licenses, etc.

OpenAPI specification builds upon JSON Schema.

Endpoints

An endpoint is exposed in the OpenAPI specification by its relative path, declared in the paths map.

Refactor this.

Document Structure

openapi: 3.1.0
info: 
  [...]
servers:
   [...]
paths:
   [...]
components:
   [...]
webhooks:
   [...]
security:
   [...]
tags:
   [...]

openapi

The string following the openapi element is the version number of the OpenAPI specification this document uses.

info

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoObject

info:
  title: OpenAPI Example
  version: 0.2.0
  summary: An OpenAPI example application 
  description:
  termsOfService:
  contact:
  license:

title

Required element. Represents the title of the API. When imported in AWS API Gateway, the title provides the API name, unless the AWS::ApiGateway::RestApi resource explicitly specifies a title, in which case the title specified by AWS::ApiGateway::RestApi will take priority.

version

Required element. Represents the version of the API document. It is different from openapi version string.

summary

A short summary of the API.

description

A description of the API. CommonMark syntax may be used for rich text representation.

servers

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject
servers:
  - url: https://petstore.swagger.io/v2

paths

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject

paths:
 /a:
    summary:
    description: 
    get: [...]
    put: [...]
    post: [...]
    delete: [...]
    options: [...]
    head: [...]
    patch: [...]
    trace: [...]
    servers:
    parameters:
 /b:
   [...]
 /c:
   [...]

Contains a map of relative paths to individual endpoints.

For syntax of individual path specifications, see:

OpenAPI Specification Path

components

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject

components:
  schemas:
    Pet:
      [...]
    Error:
      [...]

schemas

The /components/schemas section of the OpenAPI specification defines reusable objects.

OpenAPI Specification Schemas

webhooks

A map of path item objects or reference objects.

security

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject

tags

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject

Data Types

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#data-types

OAS data types are based on those supported by JSON Schema Specification Draft 2020-12

Type Format Comments
null A JSON "null" value. JSON Schema Specification type.
boolean A "true" or "false" value. JSON Schema Specification type.
object An unordered set of properties mapping a string to an instance. JSON Schema Specification type.
array An ordered list of instances. JSON Schema Specification type.
number An arbitrary-precision, base-10 decimal number value. JSON Schema Specification type.
string A string of Unicode code points. JSON Schema Specification type.
integer int32 Signed 32 bits. Introduced by OAS.
integer int64 Signed 64 bits (long). Introduced by OAS.
number float Introduced by OAS.
number double Introduced by OAS.
string password A hint to UIs to obscure input. Introduced by OAS.
string date See github.com/oapi-codegen/runtime/types/date.go
string email See github.com/oapi-codegen/runtime/types/email.go
string file See github.com/oapi-codegen/runtime/types/file.go
string uuid See github.com/oapi-codegen/runtime/types/uuid.go

$ref

OpenAPI Operation Declaration and Implementation Examples

OpenAPI Examples