OpenAPI Introduction

& Workflow

What is OpenAPI?

A configuration file (JSON or YAML) that describes API requests and responses.

Before version 3 was released, OpenAPI was known as Swagger.

Swagger still exists as a company that provides tooling and services around OpenAPI.

What can OpenAPI do?

Documentation
Requests & response validation
Writing tests
Powering mock servers
Code generation

How do you write OpenAPI?

Raw JSON or YAML
- Swagger Editor
- Stoplight
- IDE plugin
Auto-generated from doc blocks
GUI editor
- Stoplight

How do you write OpenAPI?

Raw JSON or YAML
- Swagger Editor
- Stoplight
- IDE plugin
Auto-generated from doc blocks
GUI editor
- Stoplight

Open API Spec

https://swagger.io/docs/specification/basic-structure/

Top-level Properties

{
    "openapi": "3.0.0",
    "info": {},
    "tags": [],
    "servers": [],
    "components": {},
    "paths": {}
}

Components

{
    "parameters": {},
    "responses": {},
    "schemas": {}
}

Parameters

"parameters": {
    "PageNumber": {
        "name": "page",
        "in": "query",
        "description": "The page number requested.",
        "schema": {
            "type": "number",
            "example": 1
        }
    }
}

Parameters are common variables that can exist in the URL query, the URL path, headers, or cookies.

They can also be defined on individual requests.

Responses

"responses": {
    "200SuccessfulResponse": {
    "description": "Successful response",
    "content": {
        "application/json": {
            "schema": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    }
                }
            }
        }
    }
}

Stores responses that may be shared across various requests

Schemas

"Region": {
    "title": "Region",
    "description": "A Region model",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "example": "483"
        },
        "type": {
            "type": "string",
            "enum": [
                "regions"
            ]
        },
        "attributes": {
            ...
        }
    }
},

Stores descriptions of any kind of data in your requests or responses.

Writing Schemas

Schema descriptions in OpenAPI are based on an old draft of JSON Schema, but they are both a subset *and* a superset.

https://swagger.io/docs/specification/data-models/

Using this format, you can describe a data model's:

data type (e.g. 'integer', 'object')
allowable values (via 'enum')
validations (e.g. '> 5')

Simple Data Types

"name": {
    "type": "string",
    "example": "Example Name",
    "title": "Name",
    "description": "The model's name."
},
"show_feedback_review_links": {
  "type": "integer",
  "maximum": 5,
  "nullable": true
}

Required Properties

"attributes": {
    "type": "object",
    "required": [
        "name"
    ],
    "properties": {
        "name": {}
    }
}

Objects

"attributes": {
    "type": "object",
    "properties": {
        "name": {}
    }
}

Arrays

"location_ids": {
  "type": "array",
  "items": {
    "type": "integer"
  }
}

"attributes": {
    "type": "object",
    "additionalProperties": {
        "type": "string"
    }
}

Combining Schemas

The keywords `oneOf`, `anyOf`, and `allOf` allow you to validate against multiple schemas.

`allOf` will validate a model against *all* of the subschemas

"LocationFull": {
    "type": "object",
    "properties": {
        "attributes": {
            "allOf": [
                {"$ref": "#/components/schemas/LocationAttributes"},
                {"$ref": "#/components/schemas/LocationPatchAttributes"}
            ]
        }
    }
}

Shared Schemas

Schemas that are stored in the top-level `components` property can be referenced elsewhere in the document using the `$ref` key. This also works for parameters and responses.

"data": {
    "type": "object",
    "properties": {
        "attributes": {
            "$ref": "#/components/schemas/FooAttributes"
        }
    }
}

Combining Schemas

The keywords `oneOf`, `anyOf`, and `allOf` allow you to validate against multiple schemas.

`allOf` will validate a model against *all* of the subschemas

"LocationFull": {
    "type": "object",
    "properties": {
        "attributes": {
            "allOf": [
                {"$ref": "#/components/schemas/LocationAttributes"},
                {"$ref": "#/components/schemas/LocationPatchAttributes"}
            ]
        }
    }
}

Paths

"paths": {
    "/foo": {
        "get": {},
        "post": {}
    }
},
"paths": {
    "/foo/{fooId}": {
        "get": {},
        "patch": {},
        "delete": {}
    }
}

Operation

"post": {
    "operationId": "CreateFoo",
    "description": "Create Foo",
    "requestBody": {},
    "responses": {
        "200": {},
        "401": {},
        "404": {}
    }
}

Requests & Responses

{
    "description": "Successful response",
    "content": {
        "application/json": {
            "schema": {
                "type": "object",
                "properties": {
                    "token": {
                        "type": "string"
                    }
                }
            }
        }
    }
}