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"
                    }
                }
            }
        }
    }
}

deck

By Daniel Abernathy

Made with Slides.com

deck

  • 949

More from Daniel Abernathy