OpenAPI Specification

External

• OpenAPI 3.1.0 Specification https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
• https://swagger.io/specification/

Internal

• OpenAPI
• API Concepts
• REST and Hypermedia
• Amazon API Gateway Integration
• JSON Schema

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

Parameters

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

get:
  [...]
  parameters:
    - name: id
      in: path|query|header|cookie
      description:
      required: true|false
      deprecated: true|false
      allowEmptyValue: true|false
      schema: [...]
    - [...]

An operation accepts multiple parameters.

A unique parameter is defined by a combination of its name, defined as value of the name field, and its location, defined as value of the in field. The name value is required and case sensitive.

There are four possible parameter locations: "query", "header", "path", "cookie".

Parameter Locations

Path Parameters

A path parameter is declared as in: path in the OpenAPI specification file, and is a URL fragment at the left side of the question mark in the URL. For "path" parameters, the parameter name must correspond to a template expression occurring in the path field. The parameter value is actually part of the operation's URL. Also, the required property is required and the value must be true.

 /query/{id}

paths:
 /query/{id}:
   get:
     - name: id
       in: path
       required: true
       [...]

Also see:

REST Path Parameters

Query Parameters

A query parameter is declared as in: query in the OpenAPI specification file, and it is an URL fragment that follows the question mark in the full URL.

allowEmptyValue field is valid only for query parameters and allows sending a parameter with an empty value. The default value is false. Use of this property is not recommended and it is likely to be removed in a later revision.

Also see:

REST Query Parameters

Header Parameters

Header parameters are key value pairs that can be used to configure the behavior of the API.

Also see:

REST Request Headers

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

Examples

GET with Empty Response Body

paths:
  /a:
    get:
      parameters:
        - name: test
          in: query
          type: string
      responses:
        200:
          schema:
            $ref: '#/components/schemas/Empty'
components:
  schemas:
    Empty:
      type: object

A Simple CRUD REST Application with OpenAPI

A Simple CRUD REST Application with OpenAPI

TODEPLETE

Response

Response Object

Describing Responses in OpenAPI 2.0

A response is defined by its HTTP status code and the data returned in the response body and/or headers.

200:
  description: 200 response
  schema:
    $ref: '#/definitions/Empty'
    originalRef: '#/definitions/Empty'
  headers:
    Access-Control-Allow-Origin:
      type: 'string'
    Access-Control-Allow-Methods:
      type: 'string'
    Access-Control-Allow-Headers:
      type: 'string'

description

The description is required. Represents a short description of the response.

Response Body

schema

The schema keyword is used to describe the response body. A schema may define:

• a primitive type such as "string" or "number", used for plain text responses. Note that Amazon API Gateway warns if it encounters a primitive type.
• an object
• an array – typically used with JSON and XML APIs
• a file
• a reference - the schema can be defined in-line or defined at the root level of the document and referenced via $ref. This is useful if multiple responses share the same schema.

For reference models (RefModel), model.setReference("RefName") puts the model in the correct state to refer to:

definitions:
  RefName:
    type: ...

In-line schema:

responses:
  200:
    description: something
    schema:
      type: object
      properties:
        id:
          type: integer
          description: The user ID.
        username:
          type: string
          description: The user name.

This is an example that uses references:

responses:
  200:
    description: something
    schema:
      $ref: '#/definitions/User'
...
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        description: The user ID.
      username:
        type: string
        description: The user name.

"responseSchema" is sometimes used, but that seems to be deprecated.

Empty Response Body

For responses that have no body, like 204 No Content, no "schema" should be specified. This is conventionally treated as no-body response.

Response Headers

Responses can include custom headers, or headers that implement a protocol like CORS.

headers

The custom headers must be declared, under the "headers" section of the response. For OpenAPI 2.0, there is no way in Swagger to define common response headers for different response codes or different API operations. You need to define the headers for each response individually. "headers" is aA container that maps a header name to its definition. The header names are case insensitive. If a header is specified by the an extension, such as x-amazon-apigateway-integration, it has to be declared in the headers section for the corresponding response, otherwise a template error is generated.

200:
  description: 200 response
  ...
  headers:
    Access-Control-Allow-Origin:
      type: 'string'
    Access-Control-Allow-Methods:
      type: 'string'
    Access-Control-Allow-Headers:
      type: 'string'
  schema:
    $ref: '#/definitions/Empty'
    originalRef: '#/definitions/Empty'

Reference Object

CORS

CORS in Swagger

More:

CORS

x-nullable

Appears in automatically generated Swagger files, as such:

definitions:
    LibraryAccount:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          x-nullable: true

definitions:
  A:
    type: string
    title: A
    x-nullable: true

When used for an API Gateway import, it errors out as:

Unable to create model for 'LibraryAccount': Invalid model specified: Validation Result: warnings : [], errors : [Invalid model schema specified. Unsupported keyword(s): ["x-nullable"]]