├── .github ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md └── workflows │ └── sync.yaml └── reference ├── _meta.json ├── arazzo.mdx ├── assets ├── arazzo.yaml.txt └── speakeasy-bar.yaml ├── components.md ├── examples.md ├── extensions.md ├── external-documentation.md ├── index.mdx ├── info.md ├── overlays.mdx ├── paths.md ├── paths ├── _meta.json ├── operations.md ├── operations │ ├── _meta.json │ ├── callbacks.md │ ├── content.mdx │ ├── requests.md │ ├── responses.md │ └── responses │ │ ├── _meta.json │ │ ├── headers.md │ │ └── links.md ├── parameters.md └── parameters │ ├── _meta.json │ ├── cookie-parameters.md │ ├── header-parameters.md │ ├── path-parameters.md │ └── query-parameters.md ├── references.md ├── schemas.md ├── schemas ├── _meta.json ├── arrays.md ├── booleans.md ├── dataTypes.md ├── enums.md ├── null.md ├── numbers.md ├── objects.md ├── objects │ ├── _meta.json │ ├── polymorphism.md │ └── xml.md └── strings.md ├── security.md ├── security ├── security-schemes.md └── security-schemes │ ├── _meta.json │ ├── security-api-key.md │ ├── security-basic.md │ ├── security-bearer.md │ ├── security-oauth2.md │ └── security-openid.md ├── servers.md ├── servers └── server-variables.md ├── tags.md └── webhooks.md /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the inaccuracy in the documentation** 11 | A clear and concise description of what's incorrect. 12 | 13 | **Link to the relevant line in the documentation** 14 | A permalink to the [github content](./reference) is ideal 15 | 16 | **Correction** 17 | A clear and concise description of what you think the documentation should be. 18 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.github/workflows/sync.yaml: -------------------------------------------------------------------------------- 1 | 2 | name: Sync 3 | 4 | on: 5 | # push: 6 | # branches: 7 | # - main 8 | workflow_dispatch: 9 | 10 | jobs: 11 | sync: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v3 15 | - name: Copy files to another repository 16 | uses: nkoppel/push-files-to-another-repository@v1.1.3 17 | env: 18 | API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }} 19 | with: 20 | source-files: 'reference' 21 | destination-repository: 'speakeasy-registry' 22 | destination-username: 'speakeasy-api' 23 | destination-branch: 'main' 24 | destination-directory: 'web/packages/marketing-site/src/pages/openapi' 25 | commit-email: bot@speakeasyapi.dev 26 | commit-message: Sync OpenAPI Reference Documentation 27 | -------------------------------------------------------------------------------- /reference/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": { 3 | "title": "Intro to OpenAPI", 4 | "theme": { 5 | "layout": "full", 6 | "toc": false 7 | } 8 | }, 9 | "info": "Info", 10 | "servers": "Servers", 11 | "security": "Security", 12 | "tags": "Tags", 13 | "paths": "Paths", 14 | "webhooks": "Webhooks", 15 | "schemas": "Schemas", 16 | "components": "Components", 17 | "examples": "Examples", 18 | "references": "References $ref", 19 | "extensions": "Extensions", 20 | "external-documentation": "External Documentation", 21 | "overlays": { 22 | "title": "OpenAPI Overlays", 23 | "theme": { 24 | "layout": "full", 25 | "toc": false 26 | } 27 | }, 28 | "arazzo": { 29 | "title": "Arazzo: OpenAPI Workflows", 30 | "theme": { 31 | "layout": "full", 32 | "toc": false 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /reference/assets/arazzo.yaml.txt: -------------------------------------------------------------------------------- 1 | workflowsSpec: 1.0.0-prerelease 2 | info: 3 | title: Speakeasy Bar Workflows 4 | summary: Workflows for managing the Speakeasy Bar API 5 | description: > 6 | This document defines workflows for managing the [Speakeasy Bar API](https://bar.example.com), including 7 | creating new drinks, managing inventory, and processing orders. 8 | version: 4.6.3 9 | sourceDescriptions: 10 | - name: speakeasyBar 11 | url: https://bar.example.com/openapi.yaml 12 | type: openapi 13 | - name: printsAndBeeps 14 | url: https://output.example.com/workflows.yaml 15 | type: workflowsSpec 16 | workflows: 17 | - workflowId: createDrink 18 | summary: Create a new drink in the bar's menu 19 | inputs: 20 | allOf: 21 | - $ref: "#/components/inputs/authenticate" 22 | - type: object 23 | properties: 24 | drink_name: 25 | type: string 26 | drink_type: 27 | type: string 28 | drink_price_usd_cent: 29 | type: integer 30 | ingredients: 31 | type: array 32 | items: 33 | type: string 34 | steps: 35 | - stepId: authenticate 36 | operationId: authenticate 37 | parameters: 38 | - reference: $components.parameters.username 39 | - reference: $components.parameters.password 40 | - stepId: createDrink 41 | operationId: createDrink 42 | parameters: 43 | - reference: $components.parameters.authorization 44 | - name: name 45 | in: query 46 | value: $inputs.drink_name 47 | - name: type 48 | in: query 49 | value: $inputs.drink_type 50 | - name: price 51 | in: query 52 | value: $inputs.drink_price_usd_cent 53 | - name: ingredients 54 | in: query 55 | value: $inputs.ingredients 56 | - workflowId: makeDrink 57 | summary: Order a drink and check the order status 58 | inputs: 59 | - name: orderType 60 | description: The type of order 61 | type: string 62 | required: true 63 | - name: productCode 64 | description: The product code of the drink 65 | type: string 66 | required: true 67 | - name: quantity 68 | description: The quantity of the drink 69 | type: integer 70 | required: true 71 | steps: 72 | - stepId: orderDrink 73 | operationId: createOrder 74 | parameters: 75 | - name: orderType 76 | in: body 77 | value: $inputs.orderType 78 | - name: productCode 79 | in: body 80 | value: $inputs.productCode 81 | - name: quantity 82 | in: body 83 | value: $inputs.quantity 84 | - stepId: checkStatus 85 | operationId: getOrder 86 | parameters: 87 | - name: orderNumber 88 | in: path 89 | value: $orderDrink.orderNumber 90 | successCriteria: 91 | - type: simple 92 | condition: $checkStatus.status == 'completed' 93 | onSuccess: 94 | - name: printReceipt 95 | type: goto 96 | workflowId: $sourceDescriptions.printsAndBeeps.printReceipt 97 | criteria: 98 | - type: simple 99 | condition: $checkStatus.status == 'completed' 100 | onFailure: 101 | - name: beepLoudly 102 | type: goto 103 | workflowId: $sourceDescriptions.printsAndBeeps.beepLoudly 104 | criteria: 105 | - type: simple 106 | condition: $checkStatus.status == 'failed' 107 | - workflowId: addIngredient 108 | summary: Add a new ingredient to the bar's inventory 109 | inputs: 110 | - name: username 111 | description: The username of the manager 112 | type: string 113 | required: true 114 | - name: password 115 | description: The password of the manager 116 | type: string 117 | required: true 118 | - name: ingredient_name 119 | description: The name of the ingredient 120 | type: string 121 | required: true 122 | - name: ingredient_type 123 | description: The type of the ingredient 124 | type: string 125 | required: true 126 | - name: ingredient_stock 127 | description: The stock of the ingredient 128 | type: integer 129 | required: true 130 | - name: productCode 131 | description: The product code of the ingredient 132 | type: string 133 | required: true 134 | steps: 135 | - stepId: authenticate 136 | operationId: authenticate 137 | parameters: 138 | - reference: $components.parameters.username 139 | value: admin 140 | - reference: $components.parameters.password 141 | - stepId: addIngredient 142 | operationId: createIngredient 143 | parameters: 144 | - reference: $components.parameters.authorization 145 | - name: name 146 | in: query 147 | value: $inputs.ingredient_name 148 | - name: type 149 | in: query 150 | value: $inputs.ingredient_type 151 | - name: stock 152 | in: query 153 | value: $inputs.ingredient_stock 154 | - name: productCode 155 | in: query 156 | value: $inputs.productCode 157 | components: 158 | inputs: 159 | authenticate: 160 | type: object 161 | properties: 162 | username: 163 | type: string 164 | password: 165 | type: string 166 | parameters: 167 | authorization: 168 | name: Authorization 169 | in: header 170 | value: $authenticate.outputs.token 171 | username: 172 | name: username 173 | in: body 174 | value: $inputs.username 175 | password: 176 | name: password 177 | in: body 178 | value: $inputs.password 179 | -------------------------------------------------------------------------------- /reference/components.md: -------------------------------------------------------------------------------- 1 | # Components Object 2 | 3 | The Components Object is a container for reusable objects that can be referenced across the API. These objects can be referenced using [References](/openapi/references), and generally are only valid if referenced by other parts of the API. 4 | 5 | | Field | Type | Required | Description | 6 | | ----------------- | :-----------------------------------------------------------------------------------------------------------------------: | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 7 | | `schemas` | Map[string, [Schema Object](/openapi/schemas)]\* | | A map of [Schema Objects](/openapi/schemas) that can be referenced by other parts of the API.

**Note: OpenAPI 3.0.x does support [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) as the value here, but `3.1.x` uses the [JSON Schema Referencing](/openapi/schemas#json-schema--openapi) format.** | 8 | | `securitySchemes` | Map[string, [Security Scheme Object](/openapi/security/security-schemes) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Security Scheme Objects](/openapi/security/security-schemes) that can be referenced by other parts of the API. | 9 | | `pathItems` | Map[string, [Path Item Object](/openapi/paths#path-item-object) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Path Item Objects](/openapi/paths#path-item-object) that can be referenced by other parts of the API. | 10 | | `parameters` | Map[string, [Parameter Object](/openapi/paths/parameters#parameter-object) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Parameter Objects](/openapi/paths/parameters#parameter-object) that can be referenced by other parts of the API. | 11 | | `requestBodies` | Map[string, [Request Body Object](/openapi/paths/operations/requests) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Request Body Objects](/openapi/paths/operations/requests) that can be referenced by other parts of the API. | 12 | | `responses` | Map[string, [Response Object](/openapi/paths/operations/responses#response-object) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Response Objects](/openapi/paths/operations/responses#response-object) that can be referenced by other parts of the API. | 13 | | `headers` | Map[string, [Header Object](/openapi/paths/operations/responses/headers) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Header Objects](/openapi/paths/operations/responses/headers) that can be referenced by other parts of the API. | 14 | | `examples` | Map[string, [Example Object](/openapi/examples) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Example Objects](/openapi/examples) that can be referenced by other parts of the API. | 15 | | `callbacks` | Map[string, [Callback Object](/openapi/paths/operations/callbacks#callback-object) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Callback Objects](/openapi/paths/operations/callbacks#callback-object) that can be referenced by other parts of the API. | 16 | | `links` | Map[string, [Link Object](/openapi/paths/operations/responses/links#link-object) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]\* | | A map of [Link Objects](/openapi/paths/operations/responses/links#link-object) that can be referenced by other parts of the API. | 17 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the Components Object that can be used by tooling and vendors. | 18 | -------------------------------------------------------------------------------- /reference/examples.md: -------------------------------------------------------------------------------- 1 | # Examples 2 | 3 | OpenAPI examples improve your API's documentation and SDK developer experience. We can add examples to objects, parameters, or properties using either the `example` or `examples` keyword. 4 | 5 | Here's how these keywords differ: 6 | 7 | - `example`: A single [Example Object](/openapi/examples). 8 | - `examples`: A map of strings to [Example Objects](/openapi/examples). 9 | 10 | In OpenAPI 3.1, the `examples` keyword from JSON Schema is preferred. 11 | 12 | Unlike JSON Schema, the OpenAPI `examples` keyword expects an object instead of an array. 13 | 14 | It is recommended to add reusable [Example Objects](/openapi/examples) to the `components` object under the `examples` keyword. 15 | 16 | ## Example Object 17 | 18 | We can use the Example Object to add an example of a schema, parameter, or response. 19 | 20 | | Field | Type | Required | Description | 21 | | --------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | 22 | | `summary` | String | | A brief summary of the example. | 23 | | `description` | String | | A detailed description of the example. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 24 | | `value` | Any | | The example value. Mutually exclusive with the `externalValue` field. | 25 | | `externalValue` | String | | A URL that points to the example. This is useful if the example is too large to include inline. Mutually exclusive with the `value` field. | 26 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the Example Object that can be used by tooling and vendors. | 27 | 28 | The example below illustrates how to add an example to a schema: 29 | 30 | ```yaml 31 | components: 32 | examples: 33 | SugarSyrup: 34 | summary: An example of a sugar syrup ingredient. 35 | value: 36 | name: Sugar Syrup 37 | type: long-life 38 | stock: 10 39 | photo: https://speakeasy.bar/ingredients/sugar_syrup.jpg 40 | ``` 41 | 42 | The example below illustrates how to add an example to an object property: 43 | 44 | ```yaml 45 | components: 46 | schemas: 47 | Ingredient: 48 | type: object 49 | properties: 50 | name: 51 | type: string 52 | examples: 53 | - value: Sugar Syrup 54 | summary: An example of a sugar syrup ingredient. 55 | description: A sugar syrup used to sweeten cocktails. 56 | type: 57 | $ref: "#/components/schemas/IngredientType" 58 | stock: 59 | type: integer 60 | readOnly: true 61 | examples: 62 | - value: 10 63 | summary: An example of the number of units in stock. 64 | description: The number of units of the ingredient in stock, only available when authenticated. 65 | productCode: 66 | $ref: "#/components/schemas/IngredientProductCode" 67 | photo: 68 | type: string 69 | format: uri 70 | examples: 71 | - value: https://example.com/sugarsyrup.jpg 72 | ``` 73 | -------------------------------------------------------------------------------- /reference/extensions.md: -------------------------------------------------------------------------------- 1 | # Extensions 2 | 3 | Extensions allow us to add extra keywords not included in the OpenAPI Specification. This enables tooling such as SDK generators to access vendor-specific functionality directly in an OpenAPI document. 4 | 5 | Extension fields always start with `x-`. 6 | 7 | Although optional, it is conventional for vendors to further prefix their extensions with the name of the vendor. For example, Speakeasy uses extensions that start with `x-speakeasy-`. This makes it easier to track vendor extensions over time and remove unused vendor extensions in the future. 8 | 9 | The value of an extension field can be an object, array, `null`, or any primitive value. Vendors determine the values they expect for the extensions they use. 10 | 11 | | Field | Type | Description | 12 | | ----- | ---- | ---------------------------------------------------------------------------------------------------------------------- | 13 | | `^x-` | Any | An extension's value can be an object, array, primitive, or `null`. Expected values are determined by tooling vendors. | 14 | 15 | Here's an example of a Speakeasy extension that adds retries to requests made by Speakeasy-managed SDKs: 16 | 17 | ```yaml 18 | x-speakeasy-retries: 19 | strategy: backoff 20 | backoff: 21 | initialInterval: 500 # 500 milliseconds 22 | maxInterval: 60000 # 60 seconds 23 | maxElapsedTime: 3600000 # 5 minutes 24 | exponent: 1.5 25 | statusCodes: 26 | - 5XX 27 | retryConnectionErrors: true 28 | ``` 29 | -------------------------------------------------------------------------------- /reference/external-documentation.md: -------------------------------------------------------------------------------- 1 | # External Documentation Object 2 | 3 | Allows for providing information about external documentation available for the API, Operation, Tag, or Schema. 4 | 5 | | Field | Type | Required | Description | 6 | | ----- | ----- | ----- | ----- | 7 | | `url` | String | ✅ | A URL to the external documentation. | 8 | | `description` | String | | A description of the external documentation. [CommonMark syntax](https://spec.commonmark.org/) can be used to provide a rich description. | 9 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the external documentation object that can be used by tooling and vendors. | 10 | -------------------------------------------------------------------------------- /reference/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: OpenAPI Reference 3 | description: Documentation of the OpenAPI Specification 4 | --- 5 | 6 | import { Callout } from "~/components"; 7 | import { QuickLinks } from "~/features/openapi"; 8 | 9 | # OpenAPI 3.1. Reference 10 | 11 | 12 | Hi! 👋 This documentation is Open source. If you have any feedback, 13 | suggestions, or want to contribute, check out our [GitHub 14 | repo](https://github.com/speakeasy-api/openapi-reference-documentation). 15 | 16 | 17 | 47 | 48 | ## Introduction 49 | 50 | API design is important. An API that developers enjoy interacting with turns a SaaS business into a platform. However great design is only useful if it's well-documented and consistently represented across every API surface area (docs, SDKs, etc.). 51 | 52 | That is where OpenAPI comes in. Trying to manually create & maintain all your surfaces will inevitably lead to frustration and inconsistencies. Instead, if you are building a RESTful API, OpenAPI will be (should be) the source of truth that undergirds the creation of all your public surfaces (docs, SDKs, etc.). 53 | 54 |
55 |
56 | Diagram of OpenAPI-powered workflows 61 |
62 | 63 | This documentation will help you understand the OpenAPI Specification. 64 | 65 | ## What is OpenAPI and why use it? 66 | 67 | When we refer to OpenAPI, we mean the **OpenAPI Specification** - a standardized document structure for describing HTTP APIs in a way that humans and computers can understand. 68 | 69 | OpenAPI files are written as JSON or YAML, describing your API using a standard vocabulary defined by the Specification - we'll call this JSON or YAML file an **OpenAPI document**. 70 | 71 | A valid OpenAPI document describes your RESTful API and serves as the instruction set for tooling that generates API documentation, SDKs, and more. We will refer to an app or tool that reads an OpenAPI document to perform an action as an **OpenAPI tool**. Speakeasy is one such tool, a full list can be found [here](https://openapi.tools/). 72 | 73 | ### OpenAPI Document Basics 74 | 75 | Your OpenAPI document is composed of keywords (some required, some optional). Together, the document covers the key elements of your API: 76 | 77 | - What security is required to access it? 78 | - Which endpoints expose which resources? 79 | - How are those resources constructed? 80 | 81 | 82 | 83 | #### `openapi` 84 | 85 | The version of the OpenAPI Specification that the document conforms to, should be one of the [supported versions](https://github.com/OAI/OpenAPI-Specification/tree/main/versions). 86 | 87 | **Note**: Speakeasy tooling currently only supports OpenAPI Specification versions 3.0.x and 3.1.x. 88 | 89 | ```yaml openapi.yaml focus=1 90 | openapi: 3.1.0 91 | info: 92 | title: The Speakeasy Bar 93 | version: 1.0.0 94 | servers: 95 | - url: https://speakeasy.bar 96 | description: The production server 97 | security: 98 | - apiKey: [] 99 | tags: 100 | - name: drinks 101 | description: Operations related to drinks 102 | paths: 103 | /drinks: 104 | get: 105 | tags: 106 | - drinks 107 | operationId: listDrinks 108 | summary: Get a list of drinks 109 | responses: 110 | "200": 111 | description: A list of drinks 112 | content: 113 | application/json: 114 | schema: 115 | type: array 116 | items: 117 | $ref: "#/components/schemas/Drink" 118 | components: 119 | schemas: 120 | Drink: 121 | type: object 122 | title: Drink 123 | properties: 124 | name: 125 | type: string 126 | price: 127 | type: number 128 | securitySchemes: 129 | apiKey: 130 | type: apiKey 131 | name: Authorization 132 | in: header 133 | ``` 134 | 135 | --- 136 | 137 | #### `info` 138 | 139 | Contains information about the document including fields like `title`, `version`, and `description` that help to identify the purpose and owner of the document. 140 | 141 | ```yaml openapi.yaml focus=2:4 142 | 143 | ``` 144 | 145 | --- 146 | 147 | #### `servers` 148 | 149 | Contains an optional list of servers the API is available on. If not provided, the default URL is assumed to be `/`, a path relative to where the OpenAPI document is hosted. 150 | 151 | ```yaml openapi.yaml focus=5:7 152 | 153 | ``` 154 | 155 | --- 156 | 157 | #### `security` 158 | 159 | Contains an optional list of security requirements that apply to all operations in the API. If not provided, the default security requirements are assumed to be `[]`, an empty array. 160 | 161 | ```yaml openapi.yaml focus=8:9 162 | 163 | ``` 164 | 165 | --- 166 | 167 | #### `tags` 168 | 169 | Contains an optional list of tags that are generally used to group or categorize a set of [Operations](/openapi/paths/operations). 170 | 171 | ```yaml openapi.yaml focus=10:12,16:17 172 | 173 | ``` 174 | 175 | --- 176 | 177 | #### `paths` 178 | 179 | Contains the paths and operations available within the API. 180 | 181 | ```yaml openapi.yaml focus=13:28 182 | 183 | ``` 184 | 185 | --- 186 | 187 | #### `components` 188 | 189 | Contains an optional list of reusable schemas that can be referenced from other parts of the document. This improves the readability and maintainability of the document by allowing common schemas to be defined once and reused in multiple places. 190 | 191 | ```yaml openapi.yaml focus=29:42 192 | 193 | ``` 194 | 195 | --- 196 | 197 | 198 | 199 | ## Format and File Structure 200 | 201 | An OpenAPI document is a JSON or YAML file that contains either an entire API definition or a partial definition of an API and/or its components. All field names in the specification are case-sensitive unless otherwise specified. 202 | 203 | A document can be split into multiple files, and the files can be in different formats. For example, you can have a JSON file that contains the API definition and a YAML file that contains the components, or a collection of files that contain partial definitions of the API and its components. 204 | 205 | Generally, the main API definition file is called `openapi.json` or `openapi.yaml`, and the component files are called `components.json` or `components.yaml`, though this is not a requirement. 206 | 207 | Some common organizational patterns for OpenAPI documents are: 208 | 209 | - A single file that contains the entire API definition. 210 | - A main file that contains the API definition and a components file that contains the components. 211 | - This is normally achieved by using the `$ref` keyword to reference the components file from the main file. [Click here for more information on references](/openapi/references). 212 | - A collection of files that contain partial definitions of the API and its components. 213 | - Some tools support this pattern by allowing multiple files to be provided. Others, such as the Speakeasy Generator, require the individual files to be merged into a single file before being passed to the tool, which can be achieved using the Speakeasy CLI tool. [Click here for more information on the Speakeasy CLI merge tool](https://speakeasyapi.dev/docs/speakeasy-cli/merge/). 214 | 215 | ## How is this different to the official OpenAPI documentation? 216 | 217 | The goal of this documentation is to provide a practioner's guide for developers interested in understanding the impact of OpenAPI design on their downstream API surfaces. This guide prioritizes approachability and practicality over technical completeness. 218 | 219 | We've structured the documentation according to the needs of OpenAPI users of any skill level. 220 | 221 | **Which versions of the OpenAPI Specification does this documentation cover?** 222 | 223 | This documentation will cover versions `3.0.x` and `3.1.x` of the OpenAPI specification. Where there is an important difference between the two versions, we will call it out specifically, otherwise the documentation will apply to both versions. 224 | 225 | OpenAPI is a standard for describing RESTful APIs. OpenAPI allows developers to define all the core elements of an API: endpoints, request and response data formats, authentication methods, etc. 226 | 227 | There are several versions of the OpenAPI specification in circulation: 2.0 (also known as Swagger), 3.0, and 3.1. 228 | 229 | Speakeasy supports OpenAPI versions 3.0 and 3.1. We recommend developers use OpenAPI version 3.1 for all projects. The advantage of using OpenAPI version 3.1 is that it is fully compatible with [JSON Schema](https://json-schema.org/), which gives you access to a much larger ecosystem of tools and libraries. 230 | -------------------------------------------------------------------------------- /reference/info.md: -------------------------------------------------------------------------------- 1 | # Info Object 2 | 3 | The document's `info` object contains information about the document, including fields like `title`, `version`, and `description` that help to identify the purpose and owner of the document. 4 | 5 | Example: 6 | 7 | ```yaml 8 | openapi: 3.1.0 9 | info: 10 | title: The Speakeasy Bar 11 | version: 1.0.0 12 | summary: A bar that serves drinks 13 | description: A secret underground bar that serves drinks to those in the know. 14 | contact: 15 | name: Speakeasy Support 16 | url: https://support.speakeasy.bar 17 | email: support@speakeasy.bar 18 | license: 19 | name: Apache 2.0 20 | url: https://www.apache.org/licenses/LICENSE-2.0.html 21 | termsOfService: https://speakeasy.bar/terms 22 | ``` 23 | 24 | | Field | Type | Required | Description | 25 | | ---------------- | :-------------------------------: | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 26 | | `title` | String | ✅ | A name for the API contained within the document. | 27 | | `version` | String | ✅ | The version of this OpenAPI document, _not_ the version of the API or the OpenAPI Specification used. This is recommended to be a [Semantic Version](https://semver.org/). | 28 | | `summary` | String | | **(Available in OpenAPI 3.1.x ONLY)**
A short sentence summarizing the API contained with the document. | 29 | | `description` | String | | A longer description of the API contained within the document. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 30 | | `contact` | [Contact Object](#contact-object) | | Contact information for the maintainer of the API.

**Note:** Currently not supported by Speakeasy tooling. | 31 | | `license` | [License Object](#license-object) | | The license the API is made available under. | 32 | | `termsOfService` | String | | A URL to the terms of service for the API. | 33 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the info object that can be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification. | 34 | 35 | The above order of fields is recommended (but is not required by the OpenAPI specification) as it puts the most important information first and allows the reader to get a quick overview of the document and API. 36 | 37 | ## Contact Object 38 | 39 | Contact information for the maintainer of the API. 40 | 41 | | Field | Type | Required | Description | 42 | | ------- | :-----------------------: | :------: | ---------------------------------------------------------------------------------------------------------- | 43 | | `name` | String | | The name of a contact that could be approached, for example, for support. | 44 | | `url` | String | | A URL to a website or similar providing contact information. | 45 | | `email` | String | | An email address for the contact. | 46 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the contact object that can be used by tooling and vendors. | 47 | 48 | ## License Object 49 | 50 | The license the API is made available under. 51 | 52 | | Field | Type | Required | Description | 53 | | ------------ | :-----------------------: | :----------------: | --------------------------------------------------------------------------------------------------------------------------------------------- | 54 | | `name` | String | ✅ | The name of the license. | 55 | | `identifier` | String | | **(Available in OpenAPI 3.1.x ONLY)**
An [SPDX identifier](https://spdx.org/licenses/) for the license. Provided only if `url` isn't set. | 56 | | `url` | String | | A URL to the license information. Provided only if `identifier` isn't set. | 57 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the license object that can be used by tooling and vendors. | 58 | -------------------------------------------------------------------------------- /reference/paths.md: -------------------------------------------------------------------------------- 1 | # Paths Object 2 | 3 | The `paths` object is a map of [Path Item Objects](/openapi/paths#path-item-object) that describes the available paths and operations for the API. 4 | 5 | Each path is a relative path to the servers defined in the [Servers](/openapi/servers) object, either at the document, path, or operation level. For example, if a server is defined as `https://speakeasy.bar/api` and a path is defined as `/drinks`, the full URL to the path would be `https://speakeasy.bar/api/drinks`, where the path is appended to the server URL. 6 | 7 | Example: 8 | 9 | ```yaml 10 | paths: 11 | /drinks: 12 | get: ... # operation definition 13 | /drink: 14 | get: ... # operation definition 15 | put: ... # operation definition 16 | post: ... # operation definition 17 | delete: ... # operation definition 18 | ``` 19 | 20 | | Field | Type | Required | Description | 21 | | --------- | :-----------------------------------: | :------: | -------------------------------------------------------------------------------------------------------- | 22 | | `/{path}` | [Path Item Object](/openapi/paths#path-item-object) | | A relative path to an individual endpoint, where the path **_must_** begin with a `/`. | 23 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the paths object that can be used by tooling and vendors. | 24 | 25 | ## Path Item Object 26 | 27 | A Path Item Object describes the operations available on a single path. This is generally a map of HTTP methods to [Operation Objects](/openapi/paths/operations) that describe the operations available. 28 | 29 | It is possible to override the [Servers](/openapi/servers) defined at the document level for a specific path by providing a list of [Server Objects](/openapi/servers) at the path level. 30 | 31 | It is also possible to provide a list of [Parameters](/openapi/paths/parameters) that are common to all operations defined on the path. 32 | 33 | Example: 34 | 35 | ```yaml 36 | paths: 37 | /drinks: 38 | summary: Various operations for browsing and searching drinks 39 | description: 40 | servers: # Override the servers defined at the document level and apply to all operations defined on this path 41 | - url: https://drinks.speakeasy.bar 42 | description: The drinks server 43 | parameters: # Define a list of parameters that are common to all operations defined on this path 44 | - name: type 45 | in: query 46 | schema: 47 | type: string 48 | enum: 49 | - cocktail 50 | - mocktail 51 | - spirit 52 | - beer 53 | - wine 54 | - cider 55 | get: ... # operation definition 56 | ``` 57 | 58 | Or: 59 | 60 | ```yaml 61 | paths: 62 | /drinks: 63 | $ref: "#/components/pathItems/drinks" # Reference a Path Item Object defined in the Components Object allowing for reuse in different paths 64 | components: 65 | pathItems: 66 | drinks: 67 | servers: 68 | - url: https://drinks.speakeasy.bar 69 | description: The drinks server 70 | parameters: 71 | - name: type 72 | in: query 73 | schema: 74 | type: string 75 | enum: 76 | - cocktail 77 | - mocktail 78 | - spirit 79 | - beer 80 | - wine 81 | - cider 82 | get: ... # operation definition 83 | ``` 84 | 85 | | Field | Type | Required | Description | 86 | | ------------- | :-----------------------------------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 87 | | `$ref` | String | | Allows for referencing a [Path Item Object](/openapi/paths#path-item-object) defined in the [Components Object](/openapi/components) under the `pathItems` field. If used, no other fields should be set. | 88 | | `summary` | String | | A short summary of what the path item represents. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 89 | | `description` | String | | A description of the path item. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 90 | | `servers` | [Servers](/openapi/servers) | | A list of [Server Objects](/openapi/servers) that override the servers defined at the document level. Applies to all operations defined on this path. | 91 | | `parameters` | [Parameters](/openapi/paths/parameters) | | A list of [Parameter Objects](/openapi/paths/parameters#parameter-object) that are common to all operations defined on this path. | 92 | | `get` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`GET` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET). | 93 | | `put` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`PUT` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT). | 94 | | `post` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`POST` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST). | 95 | | `delete` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`DELETE` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE). | 96 | | `options` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`OPTIONS` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS). | 97 | | `head` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`HEAD` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD). | 98 | | `patch` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`PATCH` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH). | 99 | | `trace` | [Operation Object](/openapi/paths/operations) | | An operation associated with the [`TRACE` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE). | 100 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the Path Item Object that can be used by tooling and vendors. | 101 | 102 | The order of fields above is recommended but is not significant to the order in which the endpoints should be used. -------------------------------------------------------------------------------- /reference/paths/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "parameters": "Parameters", 3 | "operations": "Operations" 4 | } 5 | -------------------------------------------------------------------------------- /reference/paths/operations.md: -------------------------------------------------------------------------------- 1 | # Operation Object 2 | 3 | An operation object describes a single API operation within a path, including all its possible inputs and outputs and the configuration required to make a successful request. 4 | 5 | Each operation object corresponds to an HTTP verb, such as `get`, `post`, or `delete`. 6 | 7 | Example: 8 | 9 | ```yaml 10 | paths: 11 | /drinks: 12 | get: 13 | # The Operation Object 14 | operationId: listDrinks 15 | summary: Get a list of drinks. 16 | description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information. 17 | security: 18 | - {} 19 | tags: 20 | - drinks 21 | parameters: 22 | - name: type 23 | in: query 24 | description: The type of drink to filter by. If not provided all drinks will be returned. 25 | required: false 26 | schema: 27 | $ref: "#/components/schemas/DrinkType" 28 | responses: 29 | "200": 30 | description: A list of drinks. 31 | content: 32 | application/json: 33 | schema: 34 | type: array 35 | items: 36 | $ref: "#/components/schemas/Drink" 37 | ``` 38 | 39 | | Field | Type | Required | Description | 40 | | ------------- | :-----------------------------------------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 41 | | `operationId` | String | | A unique identifier for the operation, this **_must_** be unique within the document, and is **_case sensitive_**. It is **_recommended_** to always define an `operationId`, but is not required. | 42 | | `deprecated` | Boolean | | Whether the operation is deprecated or not. Defaults to `false`. | 43 | | `summary` | String | | A short summary of what the operation does. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 44 | | `description` | String | | A detailed description of the operation, what it does, and how to use it. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 45 | | `servers` | [Servers](/openapi/servers) | | A list of [Server Objects](/openapi/servers) that override the servers defined at the document and path levels and apply to this operation. | 46 | | `security` | [Security](/openapi/security) | | A list of [Security Requirement Objects](/openapi/security#security-requirement-object) that override the security requirements defined at the document and path levels and apply to this operation. | 47 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the operation object that can be used by tooling and vendors. | 48 | | `parameters` | [Parameters](/openapi/paths/parameters) | | A list of [Parameter Objects](/openapi/paths/parameters#parameter-object) that are available to this operation. The parameters defined here merge with any defined at the path level, overriding any duplicates. | 49 | | `requestBody` | [Request Body Object](/openapi/paths/operations/requests) | | The request body for this operation where the [HTTP method supports a request body](https://httpwg.org/specs/rfc7231.html). Otherwise, this field is ignored. | 50 | | `responses` | [Responses](/openapi/paths/operations/responses) | ✅ | A map of [Response Objects](/openapi/paths/operations/responses#response-object) that define the possible responses from executing this operation. | 51 | | `callbacks` | [Callbacks](/openapi/paths/operations/callbacks) | | A map of [Callback Objects](/openapi/paths/operations/callbacks#callback-object) that define possible callbacks that may be executed as a result of this operation. | 52 | 53 | The above order of fields is recommended for defining the fields in the document to help set the stage for the operation and provide a clear understanding of what it does. -------------------------------------------------------------------------------- /reference/paths/operations/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "content": "Content & Media Types", 3 | "requests": "Requests", 4 | "responses": "Responses", 5 | "callbacks": "Callbacks" 6 | } 7 | -------------------------------------------------------------------------------- /reference/paths/operations/callbacks.md: -------------------------------------------------------------------------------- 1 | # Callbacks 2 | 3 | A map of [Callback Objects](/openapi/paths/operations/callbacks#callback-object) or [References](/openapi/references) that define incoming requests that may be triggered by the parent operation and the expected responses to be returned. The key is a unique identifier for the collection of callbacks contained within. 4 | 5 | **Note: Callbacks are only valid on operations that also pass the required URL to call the callback on, in either the parameters or the request body of the parent operation. In the event that a request from the API is sent in reaction to calling the parent operation but the callback URL is provided elsewhere, use [webhooks](/openapi/webhooks) to document the callback instead (webhooks only available in OpenAPI 3.1.x)** 6 | 7 | For example: 8 | 9 | ```yaml 10 | /order: 11 | post: 12 | operationId: createOrder 13 | summary: Create an order. 14 | description: Create an order for a drink. 15 | tags: 16 | - orders 17 | parameters: 18 | - name: callback_url 19 | in: query 20 | description: The url to call when the order is updated. 21 | required: false 22 | schema: 23 | type: string 24 | requestBody: 25 | required: true 26 | content: 27 | application/json: 28 | schema: 29 | $ref: "#/components/schemas/Order" 30 | responses: 31 | "200": 32 | description: The order was created successfully. 33 | content: 34 | application/json: 35 | schema: 36 | $ref: "#/components/schemas/Order" 37 | "5XX": 38 | $ref: "#/components/responses/APIError" 39 | default: 40 | $ref: "#/components/responses/UnknownError" 41 | callbacks: 42 | orderUpdate: 43 | "{$request.query.callback_url}": 44 | post: 45 | summary: Receive order updates. 46 | description: Receive order updates from the supplier, this will be called whenever the status of an order changes. 47 | tags: 48 | - orders 49 | requestBody: 50 | required: true 51 | content: 52 | application/json: 53 | schema: 54 | type: object 55 | properties: 56 | order: 57 | $ref: "#/components/schemas/Order" 58 | responses: 59 | "200": 60 | description: The order update was received successfully. 61 | "5XX": 62 | $ref: "#/components/responses/APIError" 63 | default: 64 | $ref: "#/components/responses/UnknownError" 65 | ``` 66 | 67 | ## Callback Object 68 | 69 | A map of [Runtime Expressions](/openapi/references#runtime-expression) (that represent URLs the callback request is sent to) to a [Path Item Object](/openapi/paths#path-item-object) or [Reference](/openapi/references) that defines a request to be initiated by the API provider and a potential response to be returned. 70 | 71 | The expression when evaluated at runtime will resolve to a URL either represented in the parameters, request body, or response body of the parent operation. 72 | 73 | Examples: 74 | 75 | `{$request.query.callback_url}` will resolve to the value sent in the `callback_url` query parameter sent in the parent operation. 76 | 77 | `{$request.body#/asyncURL}` will resolve to the value of the `asyncURL` property in the request body of the parent operation. 78 | 79 | `{$response.body#/success/progressEndpoint}` will resolve to the value of the `progressEndpoint` property within the `success` object in the response body of the parent operation. 80 | 81 | Any number of [extension](/openapi/extensions) fields can be added to the Callback Object that can be used by tooling and vendors. -------------------------------------------------------------------------------- /reference/paths/operations/content.mdx: -------------------------------------------------------------------------------- 1 | import { Callout } from 'nextra/components' 2 | 3 | # Content and Media Types in OpenAPI 4 | 5 | In OpenAPI 3.1, the `content` keyword indicates the media types required in request bodies or returned by responses. Media types are often referred to as content types or MIME types, but we'll use media types in this document. 6 | 7 | Media types in OpenAPI inform the client how to interpret data received from the server, and which data types the server expects from the client. 8 | 9 | Common examples of media types include: 10 | 11 | - `application/json` for JSON objects. 12 | - `text/plain` for plain text. 13 | - `image/png` for PNG image files. 14 | - `application/xml` for XML files. 15 | - `multipart/form-data` for form data that can include files. 16 | 17 | ## Content Map 18 | 19 | The `content` object is a map of key-value pairs. 20 | 21 | Each key in the map is a [media or MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) like `application/json`, `text/plain`, or `image/png`. 22 | 23 | The value associated with each key is a [Media Type Object](#media-type-object) that describes the structure and other relevant details for its corresponding media type. 24 | 25 | Media type keys can include wildcards indicating a range of media types they cover. For example, `application/*` would match `application/json`, `application/xml`, and so on. It can be explicitly defined to match only a single media type, for example, `application/json; charset=utf-8`. 26 | 27 | 28 | **Avoid wildcard media types where possible:** While using wildcards in defining content types is convenient, it might lead to ambiguous results if the client and server do not handle the same range of media types. Use specific media types where possible to avoid ambiguity. 29 | 30 | 31 | Where both a wildcard and a specific media type are defined, the specific media type definition takes precedence. 32 | 33 | The example below shows a `content` map with four media types: 34 | 35 | ```yaml 36 | content: 37 | application/json: # JSON formatted content 38 | schema: 39 | $ref: "#/components/schemas/Drink" 40 | img/*: # Image formatted content of any type 41 | schema: 42 | type: string 43 | format: binary 44 | text/*: # Text-based content of any type 45 | schema: 46 | type: string 47 | text/csv: # CSV formatted content (this will take precedence over text/*) 48 | schema: 49 | $ref: "#/components/schemas/Drink" 50 | ``` 51 | 52 | In this example, the server expects one of the following types: 53 | 54 | - A JSON object representing a drink. 55 | - Any image file in binary format. 56 | - A CSV file representing a drink. 57 | - Any text file. 58 | 59 | ## Content Negotiation 60 | 61 | When the client sends a request to the server, it includes a `Content-Type` HTTP header in the request, indicating to the server how to interpret the data in the body of the request. 62 | 63 | Likewise, the server includes a `Content-Type` HTTP header in its response, which the client should use to interpret the data in the response. 64 | 65 | The client may also include an `Accept` HTTP header in a request, indicating to the server which content types the client can handle. The server should then send a response with a `Content-Type` header that matches one of the accepted types. This exchange is known as [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation). 66 | 67 | The diagram below illustrates the headers sent by the client and server during content negotiation: 68 | 69 | ```mermaid 70 | sequenceDiagram 71 | participant C as Client 72 | participant S as Server 73 | Note over C,S: Establish Connection 74 | C->>S: Request with Headers 75 | Note over C: Request headers include: 76 | Note over C: Content-Type: text/csv 77 | Note over C: Accept: application/json, application/xml 78 | S->>C: Response with Headers 79 | Note over S: Response headers include: 80 | Note over S: Content-Type: application/json 81 | ``` 82 | 83 | Note that the request and response content types do not need to match. For example, in the diagram above, the client sends a request as CSV but expects JSON or XML in response. 84 | 85 | ## Media Type Object 86 | 87 | A Media Type Object describes the request or response for a media type, with optional examples and extensions. 88 | 89 | | Field | Type | Required | Description | 90 | | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 91 | | `schema` | [Schema Object](../../schemas.md) | | A schema that describes the request or response content. | 92 | | `examples` | Map[string, [Example Object](../../examples.md) \| [OpenAPI Reference Object](../../references.md#openapi-reference-object)] | | Optional examples of the media type. These examples override any examples from the [Schema Object](../../schemas.md) in the `schema` field. Mutually exclusive with the `example` field. | 93 | | `example` | Any | | An optional example of the media type. This example overrides any examples from the [Schema Object](../../schemas.md) in the `schema` field. Mutually exclusive with the `examples` field. Deprecated in OpenAPI 3.1 in favor of `examples`. | 94 | | `encoding` | Map[string, [Encoding Object](./requests.md#encoding-object)] | | An optional map of [Encoding Objects](./requests.md#encoding-object). Each Encoding Object's key should match one of the properties from the [Schema Object](../../schemas.md) in the `schema` field. Only applies to [Request Body Objects](./requests.md) when the media type is `multipart` or `application/x-www-form-urlencoded`. | 95 | | `x-*` | [Extensions](../../extensions.md) | | Any number of extension fields as required by tooling and vendors. | 96 | 97 | ## Media Type Examples 98 | 99 | The examples below illustrate the use of the `content` object with different media types. 100 | 101 | ### JSON Media Type 102 | 103 | The example below shows a `content` object with a JSON media type: 104 | 105 | ```yaml 106 | content: 107 | application/json: 108 | schema: 109 | $ref: "#/components/schemas/Drink" 110 | examples: 111 | mojito: 112 | value: 113 | name: "Mojito" 114 | ingredients: 115 | - name: "White Rum" 116 | quantity: 50 117 | - name: "Lime Juice" 118 | quantity: 20 119 | - name: "Mint Leaves" 120 | quantity: 10 121 | ``` 122 | 123 | In this example, the server expects a JSON object representing a drink. The `examples` field provides an [Example Object](../../examples.md) of the expected JSON object. 124 | 125 | The curl command below sends a request to the server with a JSON object in the body: 126 | 127 | ```bash 128 | curl -X POST "https://api.example.com/drinks" \ 129 | -H "Content-Type: application/json" \ 130 | -d '{ 131 | "name": "Mojito", 132 | "ingredients": [ 133 | { 134 | "name": "White Rum", 135 | "quantity": 50 136 | }, 137 | { 138 | "name": "Lime Juice", 139 | "quantity": 20 140 | }, 141 | { 142 | "name": "Mint Leaves", 143 | "quantity": 10 144 | } 145 | ] 146 | }' 147 | ``` 148 | 149 | ### Image Media Type 150 | 151 | The example below shows a `content` object with an image media type: 152 | 153 | ```yaml 154 | content: 155 | image/png: 156 | schema: 157 | type: string 158 | format: binary 159 | ``` 160 | 161 | In this example, the server expects an image file in binary format. 162 | 163 | The curl command below sends a request to the server with an image file in the body: 164 | 165 | ```bash 166 | curl -X POST "https://api.example.com/images" \ 167 | -H "Content-Type: image/png" \ 168 | --data-binary @image.png 169 | ``` 170 | 171 | ### Text Media Type 172 | 173 | The example below shows a `content` object with a text media type: 174 | 175 | ```yaml 176 | content: 177 | text/plain: 178 | schema: 179 | type: string 180 | ``` 181 | 182 | In this example, the server expects a plain text file. 183 | 184 | The curl command below sends a request to the server with a text file in the body: 185 | 186 | ```bash 187 | curl -X POST "https://api.example.com/text" \ 188 | -H "Content-Type: text/plain" \ 189 | -d "Hello, World!" 190 | ``` 191 | 192 | ### CSV Media Type 193 | 194 | The example below shows a `content` object with a CSV media type: 195 | 196 | ```yaml 197 | content: 198 | text/csv: 199 | schema: 200 | $ref: "#/components/schemas/Drink" 201 | ``` 202 | 203 | In this example, the server expects a CSV file representing a drink. 204 | 205 | The curl command below sends a request to the server with a CSV file in the body: 206 | 207 | ```bash 208 | curl -X POST "https://api.example.com/csv" \ 209 | -H "Content-Type: text/csv" \ 210 | -d "Mojito,White Rum,50,Lime Juice,20,Mint Leaves,10" 211 | ``` 212 | 213 | ### Multipart Form Data 214 | 215 | The example below shows a `content` object with a multipart form data media type: 216 | 217 | ```yaml 218 | content: 219 | multipart/form-data: 220 | schema: 221 | properties: 222 | photo: 223 | description: A photo of the drink. 224 | type: string 225 | format: binary 226 | recipe: 227 | description: The recipe for the drink. 228 | type: string 229 | name: 230 | description: The name of the drink. 231 | type: string 232 | encoding: 233 | photo: 234 | contentType: image/jpeg, image/png 235 | headers: 236 | Content-Disposition: 237 | description: Specifies the disposition of the file (attachment and file name). 238 | schema: 239 | type: string 240 | default: 'form-data; name="photo"; filename="default.jpg"' 241 | allowReserved: false 242 | recipe: 243 | contentType: text/plain 244 | headers: 245 | Content-Disposition: 246 | description: Specifies the disposition of the file (attachment and file name). 247 | schema: 248 | type: string 249 | default: 'form-data; name="recipe"; filename="default.txt"' 250 | allowReserved: false 251 | name: 252 | contentType: text/plain 253 | headers: 254 | Content-Disposition: 255 | description: Specifies the disposition of the field. 256 | schema: 257 | type: string 258 | default: 'form-data; name="name"' 259 | allowReserved: false 260 | ``` 261 | 262 | In this example, the server expects a form data request with a photo of the drink, the recipe for the drink, and the name of the drink. The `encoding` field provides additional information about each part, such as the content type, headers, and whether reserved characters are allowed. 263 | 264 | The curl command below sends a request to the server with a photo file, a recipe file, and the name of the drink in the body: 265 | 266 | ```bash 267 | curl -X POST "https://api.example.com/drinks" \ 268 | -F "photo=@photo.jpg;type=image/jpeg" \ 269 | -F "recipe=@recipe.txt;type=text/plain" \ 270 | -F "name=Mocktail" 271 | ``` 272 | 273 | ## OpenAPI Content Best Practices 274 | 275 | When designing APIs with OpenAPI, consider the following best practices for content and media types: 276 | 277 | - Where possible, use the most specific media type for your content. For example, prefer `application/json` over `application/*` if your content is JSON. 278 | - When using OpenAPI 3.1, provide at least one example for each media type using the `examples` keyword to help clients understand the expected content and enrich the API documentation. 279 | -------------------------------------------------------------------------------- /reference/paths/operations/requests.md: -------------------------------------------------------------------------------- 1 | # Request Body Object 2 | 3 | The request body is used to describe the body of the request for operations that support a request body. 4 | 5 | | Field | Type | Required | Description | 6 | | ------------- | :-----------------------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------ | 7 | | `description` | String | | A description of the request body. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 8 | | `content` | [Content](/openapi/paths/operations/content) | ✅ | A map of [Media Type Objects](/openapi/paths/operations/content#media-type-object) that defines the possible media types that can be used for the request body. | 9 | | `required` | Boolean | | Whether the request body is required. Defaults to `false`. | 10 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the Request Body Object that can be used by tooling and vendors. | 11 | 12 | ## Encoding Object 13 | 14 | Only applicable to `requestBody` where the media type is `multipart` or `application/x-www-form-urlencoded`. An encoding object describes the encoding of a single property in the request schema. 15 | 16 | | Field | Type | Required | Description | 17 | | --------------- | --------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 18 | | `contentType` | String | | The content type of the field. If the field is an `object`, the default is `application/json`. If the field is an array, the default is based on the inner type. Otherwise, the default is `application/octet-stream`. Valid values are either a media type (for example, `application/json`), a wildcard media type (for example, `image/*`), or a comma-separated list of media types and wildcard media types (for example, `image/png, application/*`). | 19 | | `headers` | Map[string, [Header Object](/openapi/paths/operations/responses/headers) \| [Reference Object](/openapi/references#openapi-reference-object)] | | Only applies to `multipart` requests. Allows additional headers related to the field. For example, if the client needs to add a `Content-Disposition` for an uploaded file. A `Content-Type` header in this map will be ignored, in favor of the `contentType` field of the encoding object. | 20 | | `style` | String | | Can take one of the following values: `form`, `spaceDelimited`, `pipeDelimited`, or `deepObject`. Specifies the style of the field's serialization only in requests with media type `multipart/form-data` or `application/x-www-form-urlencoded`. See the description of `style` under [Query Parameters](/openapi/paths/parameters/query-parameters). | 21 | | `explode` | Boolean | | Only applies to requests with media type `multipart/form-data` or `application/x-www-form-urlencoded` and fields with `array` or `object` types. If `style` is `form`, the default is `true`, otherwise the default is `false`. | 22 | | `allowReserved` | Boolean | | Only applies to requests with media type `application/x-www-form-urlencoded`. Determines whether reserved characters (those allowed in literals but with reserved meanings) are allowed in the parameter's content. The default is `false`. When `true`, it allows reserved characters as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) to be included without percent-encoding. This can be useful for parameters with content such as URLs. | 23 | 24 | ```yaml 25 | paths: 26 | /drinks: 27 | post: 28 | requestbody: 29 | content: 30 | multipart/form-data: 31 | schema: 32 | properties: 33 | # ... other properties ... 34 | photo: 35 | description: A photo of the drink. 36 | type: string 37 | format: binary 38 | encoding: 39 | photo: 40 | contentType: image/jpeg, image/png 41 | headers: 42 | Content-Disposition: 43 | description: Specifies the disposition of the file (attachment and file name). 44 | schema: 45 | type: string 46 | default: 'form-data; name="photo"; filename="default.jpg"' 47 | allowReserved: false 48 | # style: form - not applicable to strings 49 | # explode: false - not applicable to strings 50 | ``` -------------------------------------------------------------------------------- /reference/paths/operations/responses.md: -------------------------------------------------------------------------------- 1 | # Responses 2 | 3 | The Responses Object is a map of [Response Objects](/openapi/paths/operations/responses#response-object) or [References](/openapi/references) to [Response Objects](/openapi/paths/operations/responses#response-object) that define the possible responses that can be returned from executing the operation. 4 | 5 | The keys in the map represent any known HTTP status codes that the API may return. The HTTP status codes can be defined like below: 6 | 7 | - Numeric Status Code - for example, `200`, `404`, or `500`. HTTP status codes are defined in [RFC 9110](https://httpwg.org/specs/rfc9110.html#overview.of.status.codes). 8 | - Status Code Wildcards - for example, `1XX`, `2XX`, `3XX`, `4XX`, or `5XX`. A wildcard that matches any status code in the range of its significant digit, for example, `2XX` represents status codes `200` to `299` inclusive. 9 | - `default` - A catch-all identifier for any other status codes not defined in the map. 10 | 11 | The map **_must_** contain at least one successful response code. 12 | 13 | All values **_must_** be defined as explicit strings (for example,`"200"`) to allow for compatibility between JSON and YAML. 14 | 15 | For example: 16 | 17 | ```yaml 18 | paths: 19 | /drinks: 20 | get: 21 | operationId: listDrinks 22 | summary: Get a list of drinks. 23 | description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information. 24 | tags: 25 | - drinks 26 | parameters: 27 | - name: type 28 | in: query 29 | description: The type of drink to filter by. If not provided all drinks will be returned. 30 | required: false 31 | schema: 32 | $ref: "#/components/schemas/DrinkType" 33 | responses: 34 | "200": 35 | description: A list of drinks. 36 | content: 37 | application/json: 38 | schema: 39 | type: array 40 | items: 41 | $ref: "#/components/schemas/Drink" 42 | "5XX": 43 | description: An error occurred interacting with the API. 44 | content: 45 | application/json: 46 | schema: 47 | $ref: "#/components/schemas/APIError" 48 | default: 49 | description: An unknown error occurred interacting with the API. 50 | content: 51 | application/json: 52 | schema: 53 | $ref: "#/components/schemas/Error" 54 | ``` 55 | 56 | Any number of [extension](/openapi/extensions) fields can be added to the responses object that can be used by tooling and vendors. 57 | 58 | ## Response Object 59 | 60 | The Response Object describes a single response that can be returned from executing an [operation](/openapi/paths/operations). 61 | 62 | | Field | Type | Required | Description | 63 | | ------------- | :-----------------------: | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------- | 64 | | `description` | String | ✅ | A description of the response. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 65 | | `headers` | [Headers](/openapi/paths/operations/responses/headers) | | A map of [Header Objects](/openapi/paths/operations/responses/headers) that defines the headers that can be returned from executing this operation. | 66 | | `content` | [Content](/openapi/paths/operations/content) | | A map of [Media Type Objects](/openapi/paths/operations/content#media-type-object) that defines the possible media types that can be returned from executing this operation. | 67 | | `links` | [Links](/openapi/paths/operations/responses/links) | | A map of [Link Objects](/openapi/paths/operations/responses/links#link-object) or [References](/openapi/references) that define the possible links that can be returned from executing this operation. | 68 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the response object that can be used by tooling and vendors. | -------------------------------------------------------------------------------- /reference/paths/operations/responses/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "links": "Links", 3 | "headers": "Headers" 4 | } 5 | -------------------------------------------------------------------------------- /reference/paths/operations/responses/headers.md: -------------------------------------------------------------------------------- 1 | # Headers 2 | 3 | A map of header names to [Header Objects](/openapi/paths/operations/responses/headers) or [References](/openapi/references) that define headers in [Response Objects](/openapi/paths/operations/responses#response-object) or [Encoding Objects](/openapi/paths/operations/requests#encoding-object). 4 | 5 | In this simplified example, the server returns three [Header Objects](/openapi/paths/operations/responses/headers) with the names `X-RateLimit-Remaining`, `Last-Modified`, and `Cache-Control`: 6 | 7 | ```yaml 8 | paths: 9 | /drinks/{productCode}: 10 | get: 11 | responses: 12 | "200" 13 | description: A drink. 14 | content: 15 | application/json: 16 | schema: 17 | $ref: "#/components/schemas/Drink" 18 | headers: 19 | X-RateLimit-Remaining: 20 | description: The number of requests left for the time window. 21 | schema: 22 | type: integer 23 | example: 99 24 | Last-Modified: 25 | description: The time at which the information was last modified. 26 | schema: 27 | type: string 28 | format: date-time 29 | example: '2024-01-26T18:25:43.511Z' 30 | Cache-Control: 31 | description: Instructions for caching mechanisms in both requests and responses. 32 | schema: 33 | type: string 34 | example: no-cache 35 | ``` 36 | 37 | ## Header Object 38 | 39 | Describes a single header. 40 | 41 | The name of a header is determined by the header's key in a `headers` map. 42 | 43 | | Field | Type | Required | Description | 44 | | ------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 45 | | `description` | String | | A description of the header. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 46 | | `required` | Boolean | | Whether the header is required. Defaults to `false`. | 47 | | `deprecated` | Boolean | | Whether the header is deprecated. Defaults to `false`. | 48 | | `schema` | [Schema Object](/openapi/schemas) | | A schema or reference to a schema that defines the type of the header. This is **_required_** unless `content` is defined.

**Note: OpenAPI 3.0.x supports [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) here as a value. OpenAPI 3.1.x uses the [JSON Schema Referencing](/openapi/schemas#json-schema--openapi) format.** | 49 | | `content` | Map[string, [Media Type Object](/openapi/paths/operations/content#media-type-object)] | | A map of [Media Type Objects](/openapi/paths/operations/content#media-type-object) that define the possible media types that can be used for the header. This is **_required_** unless `schema` is defined. | 50 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the header object to be used by tooling and vendors. | -------------------------------------------------------------------------------- /reference/paths/operations/responses/links.md: -------------------------------------------------------------------------------- 1 | # Links 2 | 3 | The Links object is a map of [Link Objects](/openapi/paths/operations/responses/links#link-object) or [References](/openapi/references) to [Link Objects](/openapi/paths/operations/responses/links#link-object) that allows for describing possible API-use scenarios between different operations. For example, if a response returns a `Drink` object, and the `Drink` object has an `ingredients` property that is a list of `Ingredient` objects, then a link can be defined to the `listIngredients` operation showing how the ingredients can be used as an input to the `listIngredients` operation. 4 | 5 | For example: 6 | 7 | ```yaml 8 | /drink/{name}: 9 | get: 10 | operationId: getDrink 11 | summary: Get a drink. 12 | description: Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information. 13 | tags: 14 | - drinks 15 | parameters: 16 | - name: name 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | responses: 22 | responses: 23 | "200": 24 | description: A drink. 25 | content: 26 | application/json: 27 | schema: 28 | $ref: "#/components/schemas/Drink" 29 | links: 30 | listIngredients: 31 | operationId: listIngredients 32 | parameters: 33 | ingredients: $response.body#/ingredients 34 | description: The list of ingredients returned by the `getDrink` operation can be used as an input to the `listIngredients` operation, to retrieve additional details about the ingredients required to make the drink. 35 | /ingredients: 36 | get: 37 | operationId: listIngredients 38 | summary: Get a list of ingredients. 39 | description: Get a list of ingredients, if authenticated this will include stock levels and product codes otherwise it will only include public information. 40 | tags: 41 | - ingredients 42 | parameters: 43 | - name: ingredients 44 | in: query 45 | description: A list of ingredients to filter by. If not provided all ingredients will be returned. 46 | required: false 47 | style: form 48 | explode: false 49 | schema: 50 | type: array 51 | items: 52 | type: string 53 | responses: 54 | "200": 55 | description: A list of ingredients. 56 | content: 57 | application/json: 58 | schema: 59 | type: array 60 | items: 61 | $ref: "#/components/schemas/Ingredient" 62 | "5XX": 63 | $ref: "#/components/responses/APIError" 64 | default: 65 | $ref: "#/components/responses/UnknownError" 66 | ``` 67 | 68 | ## Link Object 69 | 70 | The Link Object represents a possible link that can be followed from the response. 71 | 72 | | Field | Type | Required | Description | 73 | | -------------- | :-----------------------------------------------: | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 74 | | `operationId` | String | ✅ | The `operationId` of an [operation](/openapi/paths/operations) that exists in the document. Use either this field or the `operationRef` field, not both. | 75 | | `operationRef` | String | ✅ | Either a [Relative Reference](/openapi/references#relative-references) or [Absolute Reference](/openapi/references#absolute-references) to an [operation](/openapi/paths/operations) that exists in the document. Use either this field or the `operationId` field, not both. | 76 | | `description` | String | | A description of the link and intentions for its use. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 77 | | `parameters` | Map[string, any \| [\{Expression\}](/openapi/references#runtime-expression)] | | A map of parameters to pass to the linked operation. The key is the name of the parameter and the value is either a constant value or an [Expression](/openapi/references#runtime-expression) that will be evaluated.

The parameter name can also be qualified with the location of the parameter, for example, `path.parameter_name` or `query.parameter_name` | 78 | | `requestBody` | Any \| [\{Expression\}](/openapi/references#runtime-expression) | | A constant value or [Expression](/openapi/references#runtime-expression) that will be used as the request body when calling the linked operation. | 79 | | `server` | [Server Object](/openapi/servers) | | An optional server to be used by the linked operation. | 80 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the link object that can be used by tooling and vendors. | 81 | 82 | An example of `OperationRef`: 83 | 84 | ```yaml 85 | links: 86 | listIngredients: 87 | operationRef: "#/paths/~1ingredients/get" 88 | parameters: 89 | ingredients: $response.body#/ingredients 90 | 91 | # or 92 | 93 | links: 94 | listIngredients: 95 | operationRef: "https://speakeasy.bar/#/paths/~1ingredients/get" 96 | parameters: 97 | ingredients: $response.body#/ingredients 98 | ``` 99 | -------------------------------------------------------------------------------- /reference/paths/parameters.md: -------------------------------------------------------------------------------- 1 | # Parameters 2 | 3 | Parameters are used to describe inputs to an operation. Parameters can be defined at the path or operation level and are merged with any duplicates at the operation level, overriding any defined at the path level. 4 | 5 | Each parameter needs to be uniquely identified by a combination of its `name` and `in` fields in an [operation](/openapi/paths/operations). 6 | 7 | A parameter in the list can either be a [Parameter Object](/openapi/paths/parameters#parameter-object) or a [Reference](/openapi/references) to a [Parameter Object](/openapi/paths/parameters#parameter-object) defined in the [Components Object](/openapi/components) under the `parameters` field. 8 | 9 | Parameters can represent a number of different input types, including: 10 | 11 | - Path Parameters 12 | - Query Parameters 13 | - Headers 14 | - Cookies 15 | 16 | Example: 17 | 18 | ```yaml 19 | paths: 20 | /drinks/{type}: 21 | parameters: 22 | - name: type 23 | in: path 24 | description: The type of drink to filter by. 25 | required: true 26 | schema: 27 | $ref: "#/components/schemas/DrinkType" 28 | - name: Cache-Control 29 | in: header 30 | description: The cache control header. 31 | required: false 32 | schema: 33 | type: string 34 | enum: 35 | - no-cache 36 | - no-store 37 | - must-revalidate 38 | - max-age=0 39 | - max-age=3600 40 | - max-age=86400 41 | - max-age=604800 42 | - max-age=2592000 43 | - max-age=31536000 44 | get: 45 | operationId: listDrinks 46 | summary: Get a list of drinks. 47 | description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information. 48 | security: 49 | - {} 50 | tags: 51 | - drinks 52 | parameters: 53 | - name: limit 54 | in: query 55 | description: The maximum number of drinks to return. 56 | required: false 57 | schema: 58 | type: integer 59 | minimum: 1 60 | maximum: 100 61 | responses: 62 | "200": 63 | description: A list of drinks. 64 | content: 65 | application/json: 66 | schema: 67 | type: array 68 | items: 69 | $ref: "#/components/schemas/Drink" 70 | ``` 71 | 72 | ## Parameter Object 73 | 74 | | Field | Type | Required | Description | 75 | | ----------------- | :-----------------------------: | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 76 | | `name` | String | ✅ | The **case sensitive** name of the parameter. This **_must_** be unique when combined with the `in` field.

If the `in` field is `path`, then this field **_must_** be referenced in the owning path. | 77 | | `in` | String | ✅ | The type or location of the parameter. The available types are:
| 78 | | `description` | String | | A description of the parameter. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 79 | | `required` | Boolean | | Whether the parameter is required. If the `in` field is `path`, then this field is **always** required and **_must_** be `true`. Defaults to `false`. | 80 | | `deprecated` | Boolean | | Whether the parameter is deprecated. Defaults to `false`. | 81 | | `style` | String | | Describes how the parameter value will be serialized depending on the `in` field. The available styles are `matrix`, `label`, `form`, `simple`, `spaceDelimited`, `pipeDelimited`, and `deepObject`.

The default style depends on the `in` field:
See the [path](https://www.speakeasyapi.dev/openapi/paths/parameters/path-parameters), [header](https://www.speakeasyapi.dev/openapi/paths/parameters/header-parameters), [query](https://www.speakeasyapi.dev/openapi/paths/parameters/query-parameters), and [cookie](https://www.speakeasyapi.dev/openapi/paths/parameters/cookie-parameters) parameter sections for more details. | 82 | | `explode` | Boolean | | Whether the parameter value will be exploded, based on the parameter type. Defaults to `true` when `style` is `form`, otherwise `false`.

See the [path](https://www.speakeasyapi.dev/openapi/paths/parameters/path-parameters), [header](https://www.speakeasyapi.dev/openapi/paths/parameters/header-parameters), [query](https://www.speakeasyapi.dev/openapi/paths/parameters/query-parameters), and [cookie](https://www.speakeasyapi.dev/openapi/paths/parameters/cookie-parameters) parameter sections for more details. | 83 | | `schema` | [Schema Object](/openapi/schemas) | | A schema or reference to a schema that defines the type of the parameter. This is **_required_** unless `content` is defined.

**Note: OpenAPI 3.0.x supports [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) here as the value. OpenAPI 3.1.x uses the [JSON Schema Referencing](/openapi/schemas#json-schema--openapi) format.** | 84 | | `content` | [Content](/openapi/paths/operations/content) | | A map of [Media Type Objects](/openapi/paths/operations/content#media-type-object) that defines the possible media types that can be used for the parameter. This is **_required_** unless `schema` is defined. | 85 | | `allowEmptyValue` | Boolean | | Whether the parameter value can be empty. Only used if `in` is `query`. Defaults to `false`. | 86 | | `allowReserved` | Boolean | | Whether the parameter value can contain reserved characters as defined by [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986). Only used if `in` is `query`. Defaults to `false`. | 87 | | `example` | Any | | An example of the parameter's value. This is ignored if the `examples` field is defined. | 88 | | `examples` | [Examples])examples) | | A map of [Example Objects](/openapi/examples) and/or [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) that define the possible examples of the parameter's value. | 89 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the parameter object that can be used by tooling and vendors. | 90 | 91 | The order of fields above is recommended for defining fields in the document. 92 | 93 | ## Parameter Serialization 94 | 95 | Depending on the parameter's `in`, `style`, and `explode` fields and schema type, the parameter value will be serialized in different ways. Some combinations of schema type and parameter serialization are not valid and should be avoided. 96 | 97 | The `content` field can be used instead to define complex serialization scenarios for a parameter such as serializing an object to a JSON string for including in a query parameter in the URL. 98 | -------------------------------------------------------------------------------- /reference/paths/parameters/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "path-parameters": "Path Parameters", 3 | "header-parameters": "Header Parameters", 4 | "query-parameters": "Query Parameters", 5 | "cookie-parameters": "Cookie Parameters" 6 | } 7 | -------------------------------------------------------------------------------- /reference/paths/parameters/cookie-parameters.md: -------------------------------------------------------------------------------- 1 | # Cookie Parameters 2 | 3 | Cookie parameters are serialized at runtime to an HTTP cookie header. Types are generally serialized to a string representation, and only `form` style is available. 4 | 5 | Currently, cookies are not well supported by OpenAPI and this may change in the future, so using the default `style: form` and `explode: true` values results in serialization incompatible with most cookie parsers. 6 | 7 | Therefore, it is recommended to only use cookies for primitive types or arrays with `explode: false`, but the current serialization behaviors are included below for completeness. 8 | 9 | If using cookies for authentication, it is recommended to use the OpenAPI [`security`](/openapi/security) field to document a security scheme instead of a cookie parameter. 10 | 11 | ## Primitive Types As Cookies 12 | 13 | Primitive types such as `string`, `number`, `integer`, and `boolean` are serialized as a string. 14 | 15 | For the example below, we will use a cookie parameter named `drink-limit` with a value of `5`. 16 | 17 | | Style | Explode == `true` | Explode == `false` | 18 | | ------ | :-------------------------------: | :---------------------: | 19 | | `form` | `Cookie: drink-limit=5` (default) | `Cookie: drink-limit=5` | 20 | 21 | ## Simple Arrays As Cookies 22 | 23 | For simple arrays of primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `explode` field. 24 | 25 | For the example below, we will use a cookie parameter named `drink-types` with a value of `["gin", "vodka", "rum"]`. 26 | 27 | | Style | Explode == `true` | Explode == `false` | 28 | | ------ | :-------------------------------------------------------------------: | :---------------------------------: | 29 | | `form` | `Cookie: drink-types=gin&drink-types=vodka&drink-types=rum` (default) | `Cookie: drink-types=gin,vodka,rum` | 30 | 31 | ## Simple Objects As Cookies 32 | 33 | For simple objects whose fields are primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `explode` field. 34 | 35 | For the example below, we will use a cookie parameter named `drink-filter` with a value of `{"type": "cocktail", "strength": 5}`. 36 | 37 | | Style | Explode == `true` | Explode == `false` | 38 | | ------ | :------------------------------------------: | :---------------------------------------------: | 39 | | `form` | `Cookie: type=cocktail&strength=5` (default) | `Cookie: drink-filter=type,cocktail,strength,5` | 40 | 41 | ## Complex Objects and Arrays As Cookies 42 | 43 | For complex objects and arrays, serialization in a cookie parameter is only really possible using `content` and not any `style` options. 44 | 45 | For example, to serialize using JSON, the following: 46 | 47 | ```yaml 48 | parameters: 49 | - name: drink-filter 50 | in: cookie 51 | content: 52 | application/json: 53 | schema: 54 | type: object 55 | properties: 56 | type: 57 | type: array 58 | items: 59 | type: string 60 | strength: 61 | type: array 62 | items: 63 | type: integer 64 | ``` 65 | 66 | Would serialize to `Cookie: drink-filter={"type":["cocktail","mocktail"],"strength":[5,10]}`. -------------------------------------------------------------------------------- /reference/paths/parameters/header-parameters.md: -------------------------------------------------------------------------------- 1 | # Header Parameters 2 | 3 | Header parameters are serialized at runtime to the HTTP headers of the request. Types are generally serialized to a string representation, and only `simple` style is available. 4 | 5 | Explode defaults to `false`. 6 | 7 | There are a few reserved headers that cannot be used as parameter names and are enabled by other OpenAPI features: 8 | 9 | - `Accept` - Defining content types in the [Response Object](/openapi/paths/operations/responses#response-object) `content` field, documents the available values for the `Accept` header. 10 | - `Authorization` - Defining security requirements in the [Security Requirement Object](/openapi/security#security-requirement-object) `security` field, documents that the `Authorization` header is required. 11 | - `Content-Type` - Defining content types in the [Request Body Object](/openapi/paths/operations/requests) `content` field, documents that the `Content-Type` header is required and the acceptable values. 12 | 13 | If using headers for authentication, it is recommended to use the OpenAPI [`security`](/openapi/security) field to document a security scheme instead of a header parameter. 14 | 15 | ## Primitive Types As Headers 16 | 17 | Primitive types such as `string`, `number`, `integer`, and `boolean` are serialized as a string. 18 | 19 | For the example below, we will use a header parameter named `X-Drink-Limit` with a value of `5`. 20 | 21 | | Style | Explode == `true` | Explode == `false` | 22 | | -------- | :---------------: | :-------------------------: | 23 | | `simple` | `X-Drink-Type: 5` | `X-Drink-Type: 5` (default) | 24 | 25 | ## Simple Arrays As Headers 26 | 27 | For simple arrays of primitive types such as `string`, `number`, `integer`, and `boolean`, the `style` and `explode` fields have little effect on the serialization. 28 | 29 | For the example below, we will use a header parameter named `X-Drink-Types` with a value of `["gin", "vodka", "rum"]`. 30 | 31 | | Style | Explode == `true` | Explode == `false` | 32 | | -------- | :---------------------------: | :-------------------------------------: | 33 | | `simple` | `X-Drink-Type: gin,vodka,rum` | `X-Drink-Type: gin,vodka,rum` (default) | 34 | 35 | ## Simple Objects As Headers 36 | 37 | For simple objects whose fields are primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `explode` field. 38 | 39 | For the example below, we will use a header parameter named `X-Drink-Filter` with a value of `{"type": "cocktail", "strength": 5}`. 40 | 41 | | Style | Explode == `true` | Explode == `false` | 42 | | -------- | :--------------------------------------: | :------------------------------------------------: | 43 | | `simple` | `X-Drink-Type: type=cocktail,strength=5` | `X-Drink-Type: type,cocktail,strength,5` (default) | 44 | 45 | ## Complex Objects and Arrays As Headers 46 | 47 | For complex objects and arrays, serialization in a header parameter is only really possible using `content` and not any `style` options. 48 | 49 | For example, to serialize using JSON, the following: 50 | 51 | ```yaml 52 | parameters: 53 | - name: X-Drink-Filter 54 | in: header 55 | content: 56 | application/json: 57 | schema: 58 | type: object 59 | properties: 60 | type: 61 | type: array 62 | items: 63 | type: string 64 | strength: 65 | type: array 66 | items: 67 | type: integer 68 | ``` 69 | 70 | Would serialize to `X-Drink-Filter: {"type":["cocktail","mocktail"],"strength":[5,10]}`. -------------------------------------------------------------------------------- /reference/paths/parameters/path-parameters.md: -------------------------------------------------------------------------------- 1 | 2 | # Path Parameters 3 | 4 | Path parameters are serialized at runtime to the path of the URL, meaning they are generally serialized to a string representation and must adhere to the [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) specification. Reserved characters are percent-encoded (for example, `?` becomes `%3F`). 5 | 6 | By default, path parameters are serialized using `style: simple` and `explode: false` but there are a number of different serialization options available: 7 | 8 | - `style: simple` - Simple style serialization is the default serialization for path parameters, using commas (`,`) to separate multiple values. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.7). 9 | - `style: label` - Label-style serialization uses dots (`.`) to separate multiple values. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.6). 10 | - `style: matrix` - Matrix-style serialization uses semicolons (`;`) to separate multiple values. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.5). 11 | 12 | ## Primitive Types As Path Parameters 13 | 14 | Primitive types such as `string`, `number`, `integer`, and `boolean` are serialized as a string. The `style` and `explode` fields determine the prefix for the value generally. 15 | 16 | For the examples below, we will use a path parameter named `type` with a value of `cocktail` for a path-templated URL of `/drinks/{type}`. 17 | 18 | | Style | Explode == `true` | Explode == `false` | 19 | | -------- | :----------------------: | :----------------------: | 20 | | `simple` | `/drinks/cocktail` | `/drinks/cocktail` | 21 | | `label` | `/drinks/.cocktail` | `/drinks/.cocktail` | 22 | | `matrix` | `/drinks/;type=cocktail` | `/drinks/;type=cocktail` | 23 | 24 | ## Simple Arrays As Path Parameters 25 | 26 | For simple arrays of primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `style` and `explode` fields. 27 | 28 | For the examples below, we will use a path parameter named `types` with a value of `["gin", "vodka", "rum"]` for a path-templated URL of `/drinks/{types}`. 29 | 30 | | Style | Explode == `true` | Explode == `false` | 31 | | -------- | :----------------------------------------: | :-------------------------------: | 32 | | `simple` | `/drinks/gin,vodka,rum` | `/drinks/gin,vodka,rum` (default) | 33 | | `label` | `/drinks/.gin.vodka.rum` | `/drinks/.gin,vodka,rum` | 34 | | `matrix` | `/drinks/;types=gin;types=vodka;types=rum` | `/drinks/;types=gin,vodka,rum` | 35 | 36 | ## Simple Objects As Path Parameters 37 | 38 | For simple objects whose fields are primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `style` and `explode` fields. 39 | 40 | For the examples below, we will use a path parameter named `filter` with a value of `{"type": "cocktail", "strength": 5}` for a path-templated URL of `/drinks/{filter}`. 41 | 42 | | Style | Explode == `true` | Explode == `false` | 43 | | -------- | :---------------------------------: | :------------------------------------------: | 44 | | `simple` | `/drinks/type=cocktail,strength=5` | `/drinks/type,cocktail,strength,5` (default) | 45 | | `label` | `/drinks/.type=cocktail.strength=5` | `/drinks/.type,cocktail,strength,5` | 46 | | `matrix` | `/drinks/;type=cocktail;strength=5` | `/drinks/;filter=type,cocktail,strength,5` | 47 | 48 | ## Complex Objects and Arrays As Path Parameters 49 | 50 | For complex objects and arrays, serialization in a path parameter is only really possible using `content` and not any `style` options. 51 | 52 | For example, to serialize using JSON, the following: 53 | 54 | ```yaml 55 | parameters: 56 | - name: filter 57 | in: path 58 | content: 59 | application/json: 60 | schema: 61 | type: object 62 | properties: 63 | type: 64 | type: array 65 | items: 66 | type: string 67 | strength: 68 | type: array 69 | items: 70 | type: integer 71 | ``` 72 | 73 | Would serialize to `/drinks/%7B%22type%22%3A%5B%22cocktail%22%2C%22mocktail%22%5D%2C%22strength%22%3A%5B5%2C10%5D%7D`, which is the equivalent of `/drinks/{"type":["cocktail","mocktail"],"strength":[5,10]}` unencoded. -------------------------------------------------------------------------------- /reference/paths/parameters/query-parameters.md: -------------------------------------------------------------------------------- 1 | # Query Parameters 2 | 3 | Query parameters are serialized at runtime to the query string of the URL, meaning they are generally serialized to a string representation and must adhere to the [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) specification. By default, reserved characters are percent-encoded (for example, `?` becomes `%3F`) but this can be disabled by setting `allowReserved` to `true`. 4 | 5 | By default, query parameters are serialized using `style: form` and `explode: true` but there are a number of different serialization options available: 6 | 7 | - `style: form` - Form style serialization is the default serialization for query parameters. It generally uses ampersands (`&`) to separate multiple values and equals (`=`) to separate the key and value. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). 8 | - `style: pipeDelimited` - Pipe-delimited serialization uses pipes (`|`) to separate multiple values. 9 | - `style: spaceDelimited` - Space-delimited serialization uses percent-encoded spaces (`%20`) to separate multiple values. 10 | - `style: deepObject` - Deep-object serialization uses nested objects to represent the parameter value. 11 | 12 | ## Primitive Types As Query Parameters 13 | 14 | For primitive types such as `string`, `number`, `integer,` and `boolean`, the serialization is straightforward and the value is serialized as a string. The `style` and `explode` fields have little effect on the serialization. 15 | 16 | For the examples below, we will use a query parameter named `limit` with a value of `10`. 17 | 18 | | Style | Explode == `true` | Explode == `false` | 19 | | ---------------- | :-------------------------: | :----------------: | 20 | | `form` | `/query?limit=10` (default) | `/query?limit=10` | 21 | | `pipeDelimited` | `/query?limit=10` | `/query?limit=10` | 22 | | `spaceDelimited` | `/query?limit=10` | `/query?limit=10` | 23 | | `deepObject` | **NOT VALID** | **NOT VALID** | 24 | 25 | ## Simple Arrays As Query Parameters 26 | 27 | For simple arrays of primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `style` and `explode` fields. 28 | 29 | For the examples below, we will use a query parameter named `terms` with a value of `["gin", "vodka", "rum"]`. 30 | 31 | | Style | Explode == `true` | Explode == `false` | 32 | | ---------------- | :------------------------------------------------: | :------------------------------: | 33 | | `form` | `/query?terms=gin&terms=vodka&terms=rum` (default) | `/query?terms=gin,vodka,rum` | 34 | | `pipeDelimited` | `/query?terms=gin&terms=vodka&terms=rum` | `/query?terms=gin\|vodka\|rum` | 35 | | `spaceDelimited` | `/query?terms=gin&terms=vodka&terms=rum` | `/query?terms=gin%20vodka%20rum` | 36 | | `deepObject` | **NOT VALID** | **NOT VALID** | 37 | 38 | ## Simple Objects As Query Parameters 39 | 40 | For simple objects whose fields are primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `style` and `explode` fields. 41 | 42 | For the examples below, we will use a query parameter named `filter` with a value of `{"type": "cocktail", "strength": 5}`. 43 | 44 | | Style | Explode == `true` | Explode == `false` | 45 | | ---------------- | :-----------------------------------------------: | :--------------------------------------------: | 46 | | `form` | `/query?type=cocktail&strength=5` (default) | `/query?filter=type,cocktail,strength,5` | 47 | | `pipeDelimited` | `/query?type=cocktail&strength=5` | `/query?filter=type\|cocktail\|strength\|5` | 48 | | `spaceDelimited` | `/query?type=cocktail&strength=5` | `/query?filter=type%20cocktail%20strength%205` | 49 | | `deepObject` | `/query?filter[type]=cocktail&filter[strength]=5` | **NOT VALID** | 50 | 51 | There is a special case for simple objects with fields that are an array of primitive types such as `string`, `number`, `integer`, and `boolean` that can be handled by `style: deepObject` and `explode: true`. For example, for a query parameter named `filter` with a value of `{"type": ["cocktail", "mocktail"], "strength": [5, 10]}`, this will be serialized like `/query?filter[type]=cocktail&filter[type]=mocktail&filter[strength]=5&filter[strength]=10`. 52 | 53 | ## Complex Objects and Arrays As Query Parameters 54 | 55 | For complex objects and arrays, serialization in a query parameter is only really possible using `content` and not any `style` options. 56 | 57 | For example, to serialize using JSON, the following: 58 | 59 | ```yaml 60 | parameters: 61 | - name: filter 62 | in: query 63 | content: 64 | application/json: 65 | schema: 66 | type: object 67 | properties: 68 | type: 69 | type: array 70 | items: 71 | type: string 72 | strength: 73 | type: array 74 | items: 75 | type: integer 76 | ``` 77 | 78 | Would serialize to `/query?filter=%7B%22type%22%3A%5B%22cocktail%22%2C%22mocktail%22%5D%2C%22strength%22%3A%5B5%2C10%5D%7D`, which is the equivalent of `/query?filter={"type":["cocktail","mocktail"],"strength":[5,10]}` unencoded. 79 | -------------------------------------------------------------------------------- /reference/schemas.md: -------------------------------------------------------------------------------- 1 | # Schema Object 2 | 3 | The Schema Object represents any data type used as input or output in OpenAPI. Data types can be objects, arrays, or primitives such as `string`, `number`, `integer`, and `boolean`. 4 | 5 | Schema objects are sometimes referred to as _models_, _data types_, or simply, _schemas_. This is because schema types are used to model complex data types used by an API. 6 | 7 | The Schema Object is based on and extends the [JSON Schema Specification Draft 2020-12](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00). 8 | 9 | OpenAPI 3.1 uses all vocabularies from JSON Schema 2020-12, except for Format Assertion. 10 | 11 | For an overview of all JSON Schema properties, see [JSON Schema Docs > JSON Schema 2020-12](https://www.learnjsonschema.com/2020-12/). 12 | 13 | OpenAPI 3.1 changes the definition of two JSON Schema properties: 14 | 15 | - `description` - In OpenAPI this property may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. 16 | - `format` - OpenAPI extends JSON Schema data types by adding additional formats. See [Data Type Formats](/openapi/schemas/data-types). 17 | 18 | OpenAPI adds another vocabulary to JSON Schema with the following properties: 19 | 20 | | Field Name | Type | Description | 21 | | -------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 22 | | `discriminator` | [Discriminator Object](/openapi/schemas/objects/polymorphism#discriminator-object) | A discriminator object describes how to differentiate between related schemas based on the value of a field in a request or response. See [Composition and Inheritance](/openapi/schemas/objects/polymorphism). | 23 | | `xml` | [XML Object](/openapi/schemas/objects/xml) | Adds details about how the schema should be represented as XML. | 24 | | `externalDocs` | [External Documentation Object](/openapi/external-documentation) | Points to external documentation for this schema. | 25 | | `example` | Any | An example that satisfies this schema. **Deprecated:** Although valid, the use of `example` is discouraged. Use [Examples](/openapi/examples) instead. | 26 | | `x-` | [Extensions](/openapi/extensions) | Any number of extension fields can be added to the schema that can be used by tooling and vendors. | 27 | | Arbitrary properties | Any | The schema object supports arbitrary properties without the `x-` prefix. This is discouraged in favor of [Extensions](/openapi/extensions). | 28 | 29 | The example below illustrates three schema objects: `IngredientProductCode`, `Ingredient`, and `IngredientType`. 30 | 31 | ```yaml 32 | components: 33 | schemas: 34 | IngredientProductCode: 35 | description: The product code of an ingredient, only available when authenticated. 36 | type: string 37 | examples: 38 | - "AC-A2DF3" 39 | - "NAC-3F2D1" 40 | - "APM-1F2D3" 41 | Ingredient: 42 | type: object 43 | properties: 44 | name: 45 | description: The name of the ingredient. 46 | type: string 47 | examples: 48 | - Sugar Syrup 49 | - Angostura Bitters 50 | - Orange Peel 51 | type: 52 | $ref: "#/components/schemas/IngredientType" 53 | stock: 54 | description: The number of units of the ingredient in stock, only available when authenticated. 55 | type: integer 56 | examples: 57 | - 10 58 | - 5 59 | - 0 60 | readOnly: true 61 | productCode: 62 | $ref: "#/components/schemas/IngredientProductCode" 63 | photo: 64 | description: A photo of the ingredient. 65 | type: string 66 | format: uri 67 | examples: 68 | - https://speakeasy.bar/ingredients/sugar_syrup.jpg 69 | - https://speakeasy.bar/ingredients/angostura_bitters.jpg 70 | - https://speakeasy.bar/ingredients/orange_peel.jpg 71 | required: 72 | - name 73 | - type 74 | IngredientType: 75 | description: The type of ingredient. 76 | type: string 77 | enum: 78 | - fresh 79 | - long-life 80 | - packaged 81 | ``` 82 | 83 | ## JSON Schema & OpenAPI 84 | 85 | OpenAPI 3.0 was not totally compatible with JSON schema. That caused, and continues to cause, issues in tooling support. Fortunately, OpenAPI 3.1 is now a superset of JSON Schema, meaning compatibility with any valid JSon Schema document. 86 | -------------------------------------------------------------------------------- /reference/schemas/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "dataTypes": "Data Types", 3 | "strings": "Strings", 4 | "numbers": "Numbers", 5 | "booleans": "Booleans", 6 | "arrays": "Arrays", 7 | "objects": "Objects", 8 | "enums": "Enums", 9 | "null": "Null" 10 | } 11 | -------------------------------------------------------------------------------- /reference/schemas/arrays.md: -------------------------------------------------------------------------------- 1 | # array 2 | 3 | The **array** type provides a way of defining a list of other types through providing an **items** attribute that represents the schema of the type contained in the array. 4 | 5 | ```yaml 6 | # An array of string 7 | schema: 8 | type: array 9 | items: 10 | type: string 11 | 12 | # An array of objects 13 | schema: 14 | type: array 15 | items: 16 | type: object 17 | properties: 18 | name: 19 | type: string 20 | age: 21 | type: integer 22 | 23 | # An array of arbitrary things 24 | schema: 25 | type: array 26 | items: {} 27 | ``` 28 | 29 | The **array** type will support any schema that describes any other type in its items attribute including types using **oneOf/anyOf/allOf** attributes. The **array** type also has some optional attributes for additional validation: 30 | 31 | - **minItems** \- The minimum number of items the array must contain. 32 | - **maxItems** \- The maximum number of items the array must contain. 33 | - **uniqueItems** \- The array must contain only unique items. 34 | 35 | ```yaml 36 | # An array of floats that must contain at least 1 element. 37 | schema: 38 | type: array 39 | items: 40 | type: number 41 | format: float 42 | minItems: 1 43 | 44 | # An array of strings that must contain at most 10 elements. 45 | schema: 46 | type: array 47 | items: 48 | type: string 49 | maxItems: 10 50 | 51 | # An array of booleans that must contain exactly 3 elements. 52 | schema: 53 | type: array 54 | items: 55 | type: boolean 56 | minItems: 3 57 | maxItems: 3 58 | 59 | # An array of strings that must contain only unique elements. 60 | schema: 61 | type: array 62 | items: 63 | type: string 64 | uniqueItems: true 65 | ``` 66 | -------------------------------------------------------------------------------- /reference/schemas/booleans.md: -------------------------------------------------------------------------------- 1 | # boolean 2 | 3 | The boolean type is simple; it represents either **true** or **false**. Be aware that it doesn't support other truthy/falsy values like: **1** or **0**, an empty string “” or **null**. It has no additional attributes to control its format or validation. 4 | 5 | ```yaml 6 | # A boolean type 7 | schema: 8 | type: boolean 9 | ``` 10 | -------------------------------------------------------------------------------- /reference/schemas/dataTypes.md: -------------------------------------------------------------------------------- 1 | # Data Types 2 | 3 | The OpenAPI standard supports the following data types: 4 | 5 | - [Strings](/openapi/schemas/strings) - A sequence of characters. (dates, times, passwords, byte, and binary data are considered strings) 6 | - [Numbers](/openapi/schemas/numbers) - A number, either integer or floating-point. 7 | - [Booleans](/openapi/schemas/booleans) - A true or false value. 8 | - [Arrays](/openapi/schemas/arrays) - A collection of other data types. 9 | - [Objects](/openapi/schemas/objects) - A collection of key-value pairs. 10 | - [Enums](/openapi/schemas/enums) - A fixed list of possible values. 11 | - [Null](/openapi/schemas/null) - A null value. 12 | -------------------------------------------------------------------------------- /reference/schemas/enums.md: -------------------------------------------------------------------------------- 1 | # Enums 2 | 3 | The OpenAPI Specification (OAS) version 3.x supports the `enum` (enumerated list) keyword for all `schemaObject` object properties, including parameters, request bodies, and responses. The OAS defines an `enum` according to the JSON Schema Specification. The `enum` keyword restricts the value of a JSON property to a fixed set of values. It must be an array with at least one element, and each element must be unique. 4 | 5 | For example, the following code defines a property called `status` that must be one of the values `pending`, `approved`, or `rejected`: 6 | 7 | ```json 8 | { 9 | "type": "object", 10 | "properties": { 11 | "status": { 12 | "type": "string", 13 | "enum": ["pending", "approved", "rejected"] 14 | } 15 | }, 16 | "required": ["status"] 17 | } 18 | ``` 19 | 20 | Any JSON instance that validates against this schema must have a `status` property with exactly one of the three allowed values, matching case-sensitively, or the validation will fail. 21 | 22 | The `enum` keyword can be used with any JSON data type, including strings, numbers, objects, arrays, booleans, and the `null` type. The `enum` keyword is however most used with the base `string` and `integer` types. The `boolean` type is already constrained to the values `true` and `false` (and possibly `null` for a tri-state `boolean`). Using an `enum` with floating point number types generally makes little sense. 23 | 24 | Here is an OpenAPI schema that defines a `status` parameter that must be one of the values `pending`, `approved`, or `rejected`: 25 | 26 | **YAML** 27 | 28 | ```yaml 29 | parameters: 30 | status: 31 | in: query 32 | name: status 33 | required: true 34 | schema: 35 | type: string 36 | enum: 37 | - pending 38 | - approved 39 | - rejected 40 | ``` 41 | 42 | Any API request that includes this `status` parameter must have a value that is one of the three allowed values or the request will be rejected. 43 | 44 | ## Defaults 45 | 46 | Use `default` to allow clients to omit a field when calling your service. Below, if the client orders a drink without specifying a size, they'll get a medium cup. 47 | 48 | 49 | ```yaml 50 | openapi: 3.1.0 51 | info: 52 | title: Bar API 53 | version: 1.0.0 54 | paths: 55 | /orderDrink: 56 | post: 57 | operationId: orderDrink 58 | requestBody: 59 | content: 60 | application/json: 61 | schema: 62 | type: object 63 | properties: 64 | cupSize: 65 | type: string 66 | enum: 67 | - small 68 | - medium 69 | - large 70 | default: medium 71 | responses: 72 | '200': 73 | description: Order placed successfully 74 | ``` 75 | 76 | If you use a default, remember to omit `required: true` from the field. 77 | 78 | ## Enums With Names and Values 79 | 80 | A common requirement using enums is to specify a human-readable name for the enum label and a specific integer for the enum value. For example, in C#: 81 | 82 | ```c# 83 | public enum CupSize 84 | { 85 | SMALL = 10 86 | MEDIUM = 20 87 | LARGE = 50 88 | } 89 | ``` 90 | 91 | This is not possible using the `enum` keyword in OpenAPI. OpenAPI enums allow only a list of values. If you want your schema's enums to have both names and values, you can combine `oneOf` and `const`. This works only in OpenAPI version 3.1 and later. OpenAPI version 3.0 does not support `const`. 92 | 93 | Below is an example where a client can order a drink with one of three cup sizes: 94 | 95 | ```yaml 96 | openapi: 3.1.0 97 | info: 98 | title: Bar API 99 | version: 1.0.0 100 | paths: 101 | /orderDrink: 102 | post: 103 | summary: Order a drink with a specified cup size 104 | operationId: orderDrink 105 | requestBody: 106 | required: true 107 | content: 108 | application/json: 109 | schema: 110 | type: object 111 | properties: 112 | cupSize: 113 | $ref: '#/components/schemas/CupSize' 114 | responses: 115 | '200': 116 | description: Order placed successfully 117 | components: 118 | schemas: 119 | CupSize: 120 | description: Size of the cup to order, represented by a code and label. 121 | oneOf: 122 | - description: Small cup size 123 | type: object 124 | properties: 125 | size: 126 | type: integer 127 | const: 10 128 | label: 129 | type: string 130 | const: 'Small' 131 | - description: Medium cup size 132 | type: object 133 | properties: 134 | size: 135 | type: integer 136 | const: 20 137 | label: 138 | type: string 139 | const: 'Medium' 140 | - description: Large cup size 141 | type: object 142 | properties: 143 | size: 144 | type: integer 145 | const: 50 146 | label: 147 | type: string 148 | const: 'Large' 149 | ``` 150 | 151 | Below is an example call to this API: 152 | 153 | ```json 154 | { 155 | "cupSize": { 156 | "size": 20, 157 | "label": "Medium" 158 | } 159 | } 160 | ``` 161 | 162 | Note that the client has to send both the label and the value. This defeats the purpose of using an enum, where a label is a human-readable alias for the actual value. But this `oneOf` solution makes clear what options are allowed and their exact values. You'll need to decide in your design whether you want a simple `enum` or a more descriptive `oneOf`. 163 | 164 | If you are using OpenAPI 3.0 or want to use `enum`, you can use an extension attribute to give labels to enum values. Different code generators and OpenAPI tools use different extension names. Below is an example using the Speakeasy extension field: 165 | 166 | ```yaml 167 | components: 168 | schemas: 169 | CupSize: 170 | description: Size of the cup to order, represented by a numeric code with a corresponding label. 171 | type: integer 172 | enum: 173 | - 10 174 | - 20 175 | - 50 176 | x-speakeasy-enums: 177 | - Small 178 | - Medium 179 | - Large 180 | ``` 181 | 182 | Or you can simply use a text description, for human understanding and not tooling support: 183 | 184 | ```yaml 185 | components: 186 | schemas: 187 | CupSize: 188 | type: integer 189 | enum: 190 | - 10 191 | - 20 192 | - 50 193 | description: Small Medium Large 194 | ``` 195 | 196 | ## Constants for Single Value Enums 197 | 198 | Before JSON Schema 2019 was included in OpenAPI 3.1, using an enum with a single value was the only way to specify a constant. If you are still using OpenAPI 3.0, the example below is how to specify that a constant string is returned in a response: 199 | 200 | ```yaml 201 | openapi: 3.0.0 202 | info: 203 | title: Bar API 204 | version: 1.0.0 205 | paths: 206 | /orderDrink: 207 | get: 208 | operationId: orderDrink 209 | responses: 210 | '200': 211 | description: Get a drink 212 | content: 213 | application/json: 214 | schema: 215 | enum: 216 | - Here is your beverage 217 | ``` 218 | 219 | When using OpenAPI 3.1, you can use the `const` keyword whose name more clearly matches its intention than `enum` did: 220 | 221 | ```yaml 222 | openapi: 3.1.0 223 | info: 224 | title: Bar API 225 | version: 1.0.0 226 | paths: 227 | /orderDrink: 228 | get: 229 | operationId: orderDrink 230 | responses: 231 | '200': 232 | description: Get a drink 233 | content: 234 | application/json: 235 | schema: 236 | const: Here is your beverage 237 | ``` 238 | 239 | ## Nullable Enums 240 | 241 | ### OpenAPI 3.0 242 | 243 | In OpenAPI 3.0 you can use the `nullable` keyword to specify `null` as an accpeted value in an enum. Below is an example where a client can order a drink with one of three cup sizes, or no cup siz specified at all: 244 | 245 | ```yaml focus=6 246 | components: 247 | schemas: 248 | CupSize: 249 | description: Size of the cup to order, represented by a numeric code with a corresponding label. 250 | type: string 251 | nullable: true 252 | enum: 253 | - SMALL 254 | - MEDIUM 255 | - LARGE 256 | ``` 257 | 258 | ### OpenAPI 3.1 259 | 260 | OpenAPI 3.1 was intended to more closely align with the JSON Schema standard, and as such, the way to specify nullable types is different from 3.0. Instead of using the `nullable` attribute, OpenAPI 3.1 uses JSON Schema's approach of using an array of types including the `null` type. Here's the same example adapted for OpenAPI 3.1: 261 | 262 | ```yaml focus=5,10 263 | components: 264 | schemas: 265 | CupSize: 266 | description: Size of the cup to order, represented by a numeric code with a corresponding label. 267 | type: [string, null] 268 | enum: 269 | - SMALL 270 | - MEDIUM 271 | - LARGE 272 | - null 273 | ``` 274 | 275 | ## Open Enums 276 | 277 | Traditionally enums are closed, meaning that only the values listed in the enum are allowed. By contrast, open enums allow additional values beyond those explicitly defined in the spec. Open Enums can be useful in cases where your API is evolving to support new use cases. In that scenario, you may want to allow clients to send additional values that are not yet defined where their usage is on the frontier of your API's capabilities. 278 | 279 | OpenAPI 3.x currently does not natively support the description open enums directly. However, check to see if your tooling supports `x-` extension attributes. For example, [the Speakeasy extension `x-speakeasy-unknown-values`](/docs/customize-sdks/enums#open-vs-closed-enums) allows you to define an enum with additional values beyond those listed. 280 | 281 | ``` yaml focus=6 282 | components: 283 | schemas: 284 | CupSize: 285 | description: Size of the cup to order, represented by a numeric code with a corresponding label. 286 | type: [string, null] 287 | x-speakeasy-unknown-values: allow 288 | enum: 289 | - SMALL 290 | - MEDIUM 291 | - LARGE 292 | - null 293 | ``` 294 | 295 | ## Examples 296 | 297 | Below is an example from the `components` of an API for ordering drinks showing all the different data types you can use with `enum`: 298 | 299 | ```yaml 300 | components: 301 | schemas: 302 | Orders: 303 | type: object 304 | properties: 305 | cupSize: 306 | type: string 307 | enum: 308 | - small 309 | - medium 310 | - large 311 | sugarNumbers: 312 | type: integer 313 | enum: 314 | - 0 315 | - 1 316 | - 2 317 | - 3 318 | strength: 319 | type: number 320 | enum: 321 | - 0.25 322 | - 0.5 323 | - 0.75 324 | - 1.0 325 | decaffeinated: 326 | type: boolean 327 | enum: 328 | - true 329 | - false 330 | teaOrigin: 331 | type: object 332 | enum: 333 | - { country: India, region: Assam, address: { name: "The farm"} } 334 | - { country: China, region: Fujian } 335 | - { country: Japan, region: Shizuoka } 336 | - { country: Sri Lanka, region: Nuwara Eliya } 337 | sizeRange: 338 | type: array 339 | enum: 340 | - [1,10] 341 | - [11,20] 342 | ``` 343 | 344 | Date objects are not directly supported. Export your dates to ISO strings before using them in an API. 345 | 346 | ## Best Practices 347 | 348 | Enums are simple, so there are only a few things to consider when using them in your schema: 349 | 350 | - Naming conventions: Be consistent throughout your schema. If you use uppercase, like `NEW`, then stick to uppercase for all values in all enums. 351 | - Document values: Ensure that your description field explains exactly what the purpose of each enum value is. If any two values are similar, differentiate them carefully. A few extra explanatory lines in your schema can save you days of customer support queries. 352 | - Plan for extension: When you need to add new values to an enum, have you designed your schema and your server to easily adapt? How much work will clients have to do to use the new values? What about removing values or renaming them? Consider how this affects the versioning of your API and how it will be explained to clients. 353 | - Tool support: What tools will you use with your schema, such as code generators? Do they support `enum` and `const`? Do they require extension attributes? Research this before writing your schema. 354 | - Default value: Provide default values for enums with an obvious default, but avoid them where you need the client to put thought into their choice. For example, for an API that creates a web server, you would want the client to think carefully about the server size as it costs the client money. But the operating system version could easily default to the latest. 355 | -------------------------------------------------------------------------------- /reference/schemas/null.md: -------------------------------------------------------------------------------- 1 | # null 2 | 3 | ## OpenAPI 3.0.X 4 | 5 | OpenAPI 3.0.X doesn't support a `null` type but instead allows you to mark a schema as being `nullable`. This allows that type to either contain a valid value or null. 6 | 7 | ```yaml 8 | # A nullable string 9 | schema: 10 | type: string 11 | nullable: true 12 | 13 | # A nullable integer 14 | schema: 15 | type: integer 16 | format: int32 17 | nullable: true 18 | 19 | # A nullable boolean 20 | schema: 21 | type: boolean 22 | nullable: true 23 | 24 | # A nullable array 25 | schema: 26 | type: array 27 | items: 28 | type: string 29 | nullable: true 30 | 31 | # A nullable object 32 | schema: 33 | type: object 34 | properties: 35 | foo: 36 | type: string 37 | nullable: true 38 | ``` 39 | 40 | ## OpenAPI 3.1.X 41 | 42 | OpenAPI 3.1 aligned describing `null` with JSON Schema. This allows for more precise API definitions, especially for APIs that need to explicitly support null values as valid inputs or outputs. 43 | 44 | To specify that a property, item, or response can be `null`, you can use the `type` keyword with a value of `null` or combine null with other types using the `oneOf` or type array syntax. This flexibility makes it easier to accurately model your data. 45 | 46 | ```yaml 47 | # A nullable string using array syntax 48 | schema: 49 | type: [ 'null', 'string' ] 50 | 51 | # A nullable field using an array 52 | schema: 53 | type: object 54 | properties: 55 | foo: 56 | type: ['null', 'string'] 57 | 58 | # A nullable field using oneOf 59 | schema: 60 | type: object 61 | properties: 62 | foo: 63 | oneOf: 64 | - type: null 65 | - type: string 66 | ``` 67 | -------------------------------------------------------------------------------- /reference/schemas/numbers.md: -------------------------------------------------------------------------------- 1 | # numbers & integers 2 | 3 | The **number/integer** types allows the describing of various number formats through a combination of the **type** and **format** attribute, along with a number of attributes for validating the data, the spec should cover most use cases. 4 | 5 | Available formats are: 6 | 7 | | Type | Format | Explanation | Example | 8 | | --- | --- | --- | --- | 9 | | number | | Any number integer/float at any precision. | **10** or **1.9** or **9223372036854775807** | 10 | | number | float | 32-bit floating point number. | **1.9** | 11 | | number | double | 64-bit floating point number. | **1.7976931348623157** | 12 | | integer | | Any integer number. | **2147483647** or **9223372036854775807** | 13 | | integer | int32 | 32-bit integer. | **2147483647** | 14 | | integer | int64 | 64-bit integer. | 9223372036854775807 | 15 | 16 | Below are some examples of defining **number/integer** types: 17 | 18 | ```yaml 19 | # Any number 20 | schema: 21 | type: number 22 | 23 | # A 32-bit floating point number 24 | schema: 25 | type: number 26 | format: float 27 | 28 | # A 64-bit floating point number 29 | schema: 30 | type: number 31 | format: double 32 | 33 | # Any integer 34 | schema: 35 | type: integer 36 | 37 | # A 32-bit integer 38 | schema: 39 | type: integer 40 | format: int32 41 | 42 | # A 64-bit integer 43 | schema: 44 | type: integer 45 | format: int64 46 | ``` 47 | 48 | Various tools may treat a **number/integer** without a format attribute as a type capable of holding the closest representation of that number in the target language. For example, a **number** might be represented by a **double,** and an **integer** by an **int64.** Therefore, it's recommended that you **be explicit with the format of your number type and always populate the format attribute**. 49 | 50 | The **number** type also has some optional attributes for additional validation: 51 | 52 | - **minimum** \- The **minimum** inclusive number the value should contain. 53 | - **maximum** \- The **maximum** inclusive number the value should contain. 54 | - **exclusiveMinimum** \- Make the **minimum** number exclusive. 55 | - **exclusiveMaximum** \- Make the **maximum** number exclusive. 56 | - **multipleOf** \- Specify the **number/integer** is a multiple of the provided value. 57 | 58 | Some examples are below: 59 | 60 | ```yaml 61 | # An integer with a minimum inclusive value of 0 62 | schema: 63 | type: integer 64 | format: int32 65 | minimum: 10 66 | 67 | # An integer with a minimum exclusive value of 0 68 | schema: 69 | type: integer 70 | format: int32 71 | minimum: 0 72 | exclusiveMinimum: true 73 | 74 | # A float with a range between 0 and 1 75 | schema: 76 | type: number 77 | format: float 78 | minimum: 0 79 | maximum: 1 80 | 81 | # A double with an exclusive maximum of 100 82 | schema: 83 | type: number 84 | format: double 85 | maximum: 100 86 | exclusiveMaximum: true 87 | 88 | # An 64 but integer that must be a multiple of 5 89 | schema: 90 | type: integer 91 | format: int64 92 | multipleOf: 5 93 | ``` 94 | -------------------------------------------------------------------------------- /reference/schemas/objects.md: -------------------------------------------------------------------------------- 1 | # object 2 | 3 | The **object** type allows simple and complex objects, dictionaries and free form objects, along with a number of attributes to control validation. 4 | 5 | ## Fully typed object 6 | 7 | Fully typed objects can be described by providing a properties attribute that lists each property of the object and its associated type. 8 | 9 | ```yaml 10 | # A fully typed object 11 | schema: 12 | type: object 13 | properties: 14 | name: 15 | type: string 16 | age: 17 | type: integer 18 | format: int32 19 | active: 20 | type: boolean 21 | 22 | # A fully typed object with a nested object 23 | schema: 24 | type: object 25 | properties: 26 | name: 27 | type: string 28 | age: 29 | type: integer 30 | format: int32 31 | active: 32 | type: boolean 33 | address: 34 | type: object 35 | properties: 36 | street: 37 | type: string 38 | city: 39 | type: string 40 | state: 41 | type: string 42 | zip: 43 | type: string 44 | ``` 45 | 46 | Objects with properties have access to some additional attributes that allow the objects to be validated in various ways: 47 | 48 | - **required** \- A list of properties that are required. Specified at the object level. 49 | - **readOnly** \- A property that is only available in a response. 50 | - **writeOnly** \- A property that is only available in a request. 51 | 52 | ```yaml 53 | # A fully typed object with all fields required 54 | schema: 55 | type: object 56 | properties: 57 | name: 58 | type: string 59 | age: 60 | type: integer 61 | format: int32 62 | active: 63 | type: boolean 64 | required: 65 | - name 66 | - age 67 | - active 68 | 69 | # A fully typed object with only one field required 70 | schema: 71 | type: object 72 | properties: 73 | name: 74 | type: string 75 | age: 76 | type: integer 77 | format: int32 78 | active: 79 | type: boolean 80 | required: 81 | - name 82 | 83 | # A fully typed object with some field as read only 84 | schema: 85 | type: object 86 | properties: 87 | name: 88 | type: string 89 | age: 90 | type: integer 91 | format: int32 92 | active: 93 | type: boolean 94 | readOnly: true # This field is only returned in a response 95 | required: 96 | - name 97 | - age 98 | - active # This field will only be required in a response 99 | 100 | # A fully typed object with some field as write only 101 | schema: 102 | type: object 103 | properties: 104 | name: 105 | type: string 106 | age: 107 | type: integer 108 | format: int32 109 | active: 110 | type: boolean 111 | isHuman: 112 | type: boolean 113 | writeOnly: true # This field is only required in a request 114 | required: 115 | - name 116 | - age 117 | - active 118 | - isHuman # This field will only be required in a request 119 | ``` 120 | 121 | ## Using Object for Dictionaries 122 | 123 | The **object** type can also be used to describe dictionaries/maps/etc that use strings for keys and support any value type that can be described by the OpenAPI Spec. 124 | 125 | ```yaml 126 | # A dictionary of string values 127 | schema: 128 | type: object 129 | additionalProperties: 130 | type: string 131 | 132 | # A dictionary of objects 133 | schema: 134 | type: object 135 | additionalProperties: 136 | type: object 137 | properties: 138 | name: 139 | type: string 140 | age: 141 | type: integer 142 | format: int32 143 | ``` 144 | 145 | You can also describe dictionaries that will contain certain keys 146 | 147 | ```yaml 148 | # A dictionary that must contain at least the specified keys 149 | schema: 150 | type: object 151 | properties: 152 | name: 153 | type: string # Must match type of additionalProperties 154 | required: 155 | - name 156 | additionalProperties: 157 | type: string 158 | ``` 159 | 160 | When using the **additionalProperties** attribute you can also specify additional attributes to validate the number of properties in the object: 161 | 162 | - **minProperties** \- The minimum number of properties allowed in the object. 163 | - **maxProperties** \- The maximum number of properties allowed in the object. 164 | 165 | For example: 166 | 167 | ```yaml 168 | # A dictionary of string values that has at least one key. 169 | schema: 170 | type: object 171 | additionalProperties: 172 | type: string 173 | minProperties: 1 174 | 175 | # A dictionary of string values that has at most 10 keys. 176 | schema: 177 | type: object 178 | additionalProperties: 179 | type: string 180 | maxProperties: 10 181 | 182 | # A dictionary of string values that has 1 key. 183 | schema: 184 | type: object 185 | additionalProperties: 186 | type: string 187 | minProperties: 1 188 | maxProperties: 1 189 | ``` 190 | 191 | ## Free form objects 192 | 193 | The **object** type can also be used to describe any arbitrary key/value pair (where the keys are still required to be strings). 194 | 195 | ```yaml 196 | # An arbitrary object/dictionary that can contain any value. 197 | schema: 198 | type: object 199 | additionalProperties: true 200 | 201 | # An alternate way to specify an arbitrary object/dictionary that can contain any value. 202 | schema: 203 | type: object 204 | additionalProperties: {} 205 | ``` -------------------------------------------------------------------------------- /reference/schemas/objects/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "polymorphism": "OneOf, AllOf, AnyOf", 3 | "xml": "XML" 4 | } 5 | -------------------------------------------------------------------------------- /reference/schemas/objects/polymorphism.md: -------------------------------------------------------------------------------- 1 | # Composition and Inheritance 2 | 3 | OpenAPI allows us to combine object schemas using the keywords `allOf`, `anyOf`, and `oneOf`. 4 | 5 | These keywords correspond to the following logical operators: 6 | 7 | | Keyword | Operator | Description | How to use | 8 | | ------- | -------- | -------------------------------------------------------------------------------- | --------------------------------------------------------- | 9 | | `oneOf` | `XOR` | An exclusive disjunction. Instances must satisfy **exactly one of** A, B, or C. | Use for describing Union Types | 10 | | `allOf` | `AND` | A union of all subschemas. Instances must satisfy **all of** A, B, and C. | Use for describing model composition: the creation of complex schemas via the composition of simpler schemas. | 11 | | `anyOf` | `OR` | An inclusive disjunction. Instances must satisfy **at least one of** A, B, or C. | There is no established convention about how anyOf should be interpreted. **Use with extreme caution** | 12 | 13 | The example below illustrates the different composition keywords: 14 | 15 | ```yaml 16 | components: 17 | schemas: 18 | # ... Other schemas ... 19 | Negroni: 20 | description: A Negroni cocktail. Contains gin, vermouth and campari. 21 | allOf: 22 | - $ref: "#/components/schemas/Vermouth" 23 | - $ref: "#/components/schemas/Gin" 24 | - $ref: "#/components/schemas/Campari" 25 | Martini: 26 | description: A Martini cocktail. Contains gin and vermouth, or vodka and vermouth. 27 | oneOf: 28 | - $ref: "#/components/schemas/Vodka" 29 | - $ref: "#/components/schemas/Gin" 30 | - $ref: "#/components/schemas/Vermouth" 31 | Punch: 32 | description: A Punch cocktail. Contains any combination of alcohol. 33 | anyOf: 34 | - $ref: "#/components/schemas/Rum" 35 | - $ref: "#/components/schemas/Brandy" 36 | - $ref: "#/components/schemas/Whisky" 37 | - $ref: "#/components/schemas/Vodka" 38 | - $ref: "#/components/schemas/Gin" 39 | ``` 40 | 41 | ## Discriminator Object 42 | 43 | When using `oneOf` to indicate that a request body or response contains exactly one of multiple [Schema Objects](/openapi/schemas), a discriminator object can help the client or server figure out which schema is included in the request or response. 44 | 45 | The discriminator object in OpenAPI tells a client or server which field can be used to discriminate between different schemas. 46 | 47 | | Field | Type | Required | Description | 48 | | -------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | 49 | | `propertyName` | String | ✅ | The property name used to discriminate between schemas. | 50 | | `mapping` | Map[string, string] | | An optional map of values and schema reference strings. | 51 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the discriminator object that can be used by tooling and vendors. | 52 | 53 | In the example below, the Speakeasy Bar can receive one of two order types: A drink order with a bar-counter reference or an ingredient order with a delivery address: 54 | 55 | ```yaml 56 | components: 57 | responses: 58 | OrderResponse: 59 | oneOf: 60 | - $ref: "#/components/schemas/DrinkOrder" 61 | - $ref: "#/components/schemas/IngredientOrder" 62 | ``` 63 | 64 | If we include a discriminator object, the client can indicate the order type so that the server does not need to figure that out: 65 | 66 | ```yaml 67 | components: 68 | responses: 69 | OrderResponse: 70 | oneOf: 71 | - $ref: "#/components/schemas/DrinkOrder" 72 | - $ref: "#/components/schemas/IngredientOrder" 73 | discriminator: 74 | propertyName: orderType 75 | ``` 76 | 77 | In the previous example, the value of the `orderType` property will determine the order type. The value of `orderType` must match one of the schema components, so must be either `DrinkOrder` or `IngredientOrder`. 78 | 79 | To use values that don't match a schema key, a discriminator object can include a `mapping` property that maps values to schemas. Here's an example: 80 | 81 | ```yaml 82 | components: 83 | responses: 84 | OrderResponse: 85 | oneOf: 86 | - $ref: "#/components/schemas/DrinkOrder" 87 | - $ref: "#/components/schemas/IngredientOrder" 88 | discriminator: 89 | propertyName: orderType 90 | mapping: 91 | drink: "#/components/schemas/DrinkOrder" 92 | ingredient: "#/components/schemas/IngredientOrder" 93 | ``` -------------------------------------------------------------------------------- /reference/schemas/objects/xml.md: -------------------------------------------------------------------------------- 1 | # XML Object 2 | 3 | The XML Object allows us to add details about how the schema should be represented as XML. 4 | 5 | This is useful because XML has different data types and structures compared to JSON. 6 | 7 | For example, in JSON, an array is a list of values only, while in XML, array values are represented as elements with names. 8 | 9 | | Field | Type | Required | Description | 10 | | ----------- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 11 | | `name` | String | | The name of the element when the property is represented in XML. When used in `items`, the name applies to each element in the XML array. | 12 | | `namespace` | String | | The absolute URL of the XML namespace. | 13 | | `prefix` | String | | A prefix for the element's name. | 14 | | `attribute` | Boolean | | Whether the property should be represented as an XML attribute (``) instead of an XML element (`3`). Defaults to `false`, so each property is represented as an element by default. | 15 | | `wrapped` | Boolean | | Whether array elements should be wrapped in a container element. Defaults to `false`, so array elements are not wrapped by default. Only applies to arrays. | 16 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the XML object that can be used by tooling and vendors. | 17 | 18 | The examples below illustrate how XML Objects can be used: 19 | 20 | ```yaml 21 | components: 22 | schemas: 23 | Drink: 24 | type: object 25 | properties: 26 | name: 27 | type: string 28 | xml: 29 | name: drinkName 30 | namespace: http://speakeasy.bar/schemas 31 | prefix: se 32 | ingredients: 33 | type: array 34 | items: 35 | $ref: "#/components/schemas/Ingredient" 36 | xml: 37 | name: ingredients 38 | wrapped: true 39 | namespace: http://speakeasy.bar/schemas 40 | prefix: se 41 | Ingredient: 42 | type: object 43 | properties: 44 | id: 45 | type: number 46 | xml: 47 | name: ingredientId 48 | namespace: http://speakeasy.bar/schemas 49 | prefix: se 50 | attribute: true 51 | name: 52 | type: string 53 | xml: 54 | name: ingredientName 55 | namespace: http://speakeasy.bar/schemas 56 | prefix: se 57 | ``` 58 | 59 | The example above translates to the following XML example: 60 | 61 | ```xml 62 | 63 | Mojito 64 | 65 | 66 | Sugar 67 | 68 | 69 | Lime 70 | 71 | 72 | Mint 73 | 74 | 75 | 76 | ``` -------------------------------------------------------------------------------- /reference/schemas/strings.md: -------------------------------------------------------------------------------- 1 | # strings 2 | 3 | Of the primitive types (ignoring the **object** type) , the **string** type is the most flexible type available. In addition to being able to be used to represent other types (such as “true”, “100”, “{\\“some\\”: \\”object\\”}”), it supports a number of formats that overlay constraints to the type of data represented. This is useful for mapping to types in various languages if you are using the OpenAPI spec for code generation. 4 | 5 | ## Formats 6 | 7 | The string type via the OpenAPI Specification officially supports the below formats: 8 | 9 | | Type | Format | Explanation | Example | 10 | | ------ | --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ | 11 | | string | date | An [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) formatted date string | “2022-01-30” | 12 | | string | date-time | An [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) formatted date-time string | “2019-10-12T07:20:50.52Z” | 13 | | string | password | Provides a hint that the string may contain sensitive information. | “mySecretWord1234” | 14 | | string | byte | Base-64 encoded data. | “U3BlYWtlYXN5IG1ha2VzIHdvcmtpbmcgd2l0aCBBUElzIGZ1biE=” | 15 | | string | binary | Binary data, used to represent the contents of a file. | “01010101110001” | 16 | 17 | The **format** attribute can also be used to describe a number of other formats the string might represent but outside the official list above, those formats might not be supported by tooling that works with the OpenAPI Spec, meaning that they would be provided more as hints to end-users of the API: 18 | 19 | - email 20 | - uuid 21 | - uri 22 | - hostname 23 | - ipv4 & ipv6 24 | - and others 25 | 26 | Below are some examples of describing various string types: 27 | 28 | ```yaml 29 | # A basic string 30 | schema: 31 | type: string 32 | 33 | # A string that represents a RFC3339 formatted date-time string 34 | schema: 35 | type: string 36 | format: date-time 37 | 38 | # A string that represents a enum with the specified values 39 | schema: 40 | type: string 41 | enum: 42 | - "one" 43 | - "two" 44 | - "three" 45 | 46 | # A string that represents a file 47 | schema: 48 | type: string 49 | format: binary 50 | ``` 51 | 52 | ## Patterns 53 | 54 | The **string** type also has an associated **pattern** attribute that can be provided to define a regular expression that should be matched by any string represented by that type. **The format of the regular expression is based on** [**Javascript**](https://262.ecma-international.org/5.1/#sec-15.10.1) and therefore could describe regular expressions that might not be supported by various tools or target languages, so **make sure to check the compatibility with your intended targets**. 55 | 56 | Example of a string defined with a regex pattern: 57 | 58 | ```yaml 59 | # A string that must match the specified pattern 60 | schema: 61 | type: string 62 | pattern: ^[a-zA-Z0-9_]*$ 63 | ``` 64 | -------------------------------------------------------------------------------- /reference/security.md: -------------------------------------------------------------------------------- 1 | # Security 2 | 3 | When designing an API, it is important to consider the security requirements for accessing the API. OpenAPI 3.1 provides a way to define security requirements at both the document and operation levels. 4 | 5 | Security requirements are defined as a list of [Security Requirement Objects](/openapi/security#security-requirement-object) in the `security` section. Each object in the list represents a set of security requirements that must be satisfied to access the API. 6 | 7 | To add security to an API as a whole, the `security` keyword must be defined at the [document](/openapi#openapi-document-structure) level. 8 | 9 | Likewise, to add security to a specific operation, the `security` keyword must be defined at the [operation](/openapi/paths/operations) level. 10 | 11 | Security requirements defined at the operation level override the security requirements defined at the document level. 12 | 13 | If not provided at the document level, the default security requirements are assumed to be `[]`, an empty array, meaning no security is required to access the API. 14 | 15 | The following example requires an API key to access the API: 16 | 17 | ```yaml 18 | security: 19 | - apiKey: [] 20 | components: 21 | securitySchemes: 22 | apiKey: 23 | type: apiKey 24 | name: Authorization 25 | in: header 26 | ``` 27 | 28 | In valid OpenAPI 3.1, the [Security Requirement Objects](/openapi/security#security-requirement-object) listed in `security` sections may only reference [Security Scheme Objects](/openapi/security/security-schemes) that are defined in the [Components Object](/openapi/components) under the `securitySchemes` field. In other words, the `security` section may not contain inline security schemes, and it may not contain security schemes that are not defined yet. 29 | 30 | ## Security Requirement Object 31 | 32 | A Security Requirement Object defines a map of security scheme names to [scopes or roles](#security-requirement-scopes-or-roles) that are required to access the API. The names **_must_** match the names of [Security Scheme Objects](/openapi/security/security-schemes) defined in the [Components Object](/openapi/components) under the `securitySchemes` field. 33 | 34 | | Field | Type | Required | Description | 35 | | ---------------------- | :------------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 36 | | `{securitySchemeName}` | List\ | | A list of [scopes or roles](#security-requirement-scopes-or-roles) required for the security scheme. If the security scheme type is `oauth2` or `openIdConnect`, this is a list of scope names required by the API consumer to be able to access or use the API. For any other type, this could contain a list of roles or similar required for the API consumer to obtain to authenticate with the API. | 37 | 38 | ## Supported Security Schemes 39 | 40 | Before referencing a [Security Scheme](./security/security-schemes.md) as a requirement in the `security` section, it must be defined in the [Components Object](/openapi/components) under the `securitySchemes` field. 41 | 42 | OpenAPI 3.1 supports the following security schemes: 43 | 44 | - [API Key](./security/security-schemes/security-api-key.md) 45 | - [Basic HTTP](./security/security-schemes/security-basic.md) 46 | - [Bearer Token](./security/security-schemes/security-bearer.md) 47 | - [OAuth 2.0](./security/security-schemes/security-oauth2.md) 48 | - [OpenID Connect](./security/security-schemes/security-openid.md) 49 | - Digest 50 | - Mutual TLS 51 | 52 | ## Expressing Security Requirements 53 | 54 | The `security` keyword can be used in the following ways to express security requirements. 55 | 56 | ### Disabling Security 57 | 58 | Security can be _disabled_ for a specific operation by providing an empty array (`[]`) in the list of security requirements. 59 | 60 | In this example, the `POST` operation in the `/auth` path does not require security: 61 | 62 | ```yaml 63 | paths: 64 | /auth: 65 | post: 66 | operationId: authenticate 67 | summary: Authenticate with the API 68 | security: [] # Disable security for this operation 69 | # ... 70 | ``` 71 | 72 | ### Optional Security 73 | 74 | Security can also be made optional by providing an empty object (`{}`) in the list of security requirements. 75 | 76 | In this example, the API may be accessed with or without an API key: 77 | 78 | ```yaml 79 | security: 80 | - apiKey: [] 81 | - {} 82 | ``` 83 | 84 | ### Adding Optional Security to a Specific Operation 85 | 86 | Security can be made _optional_ for a specific operation by providing an empty object (`{}`) in the list of security requirements. 87 | 88 | This does not disable the security requirements defined at the document level, but makes them optional for this specific operation. 89 | 90 | In this example, the `GET` operation in the `/drinks` path _may_ be accessed with or without an API key, but if authenticated, the response will include additional information: 91 | 92 | ```yaml 93 | paths: 94 | /drinks: 95 | get: 96 | operationId: listDrinks 97 | summary: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information 98 | security: 99 | - {} # Make security optional for this operation 100 | # ... 101 | ``` 102 | 103 | ### Allowing a Choice of Security Schemes 104 | 105 | To allow users to choose between multiple different security requirements, define the `security` keyword as a list of [Security Requirement Objects](/openapi/security#security-requirement-object). The API consumer can choose one of the requirements to authenticate. 106 | 107 | In this example, the API may be accessed with an API key **OR** OAuth 2.0: 108 | 109 | ```yaml 110 | security: # apiKey OR oauth2 can be used 111 | - apiKey: [] 112 | - oauth2: 113 | - read 114 | - write 115 | ``` 116 | 117 | ### Requiring Multiple Security Schemes Together 118 | 119 | If multiple schemes are required together, then the [Security Requirement Object](/openapi/security#security-requirement-object) should be defined with multiple security schemes. 120 | 121 | In this example, both an API key **AND** basic auth are required to access the API: 122 | 123 | ```yaml 124 | security: # both apiKey AND basic is required 125 | - apiKey: [] 126 | basic: [] 127 | ``` 128 | 129 | ### Complex Authorization Scenarios 130 | 131 | This **AND**/**OR** logic along with optional (`{}`) security can be used in any combination to express complex authorization scenarios. 132 | 133 | In this example, the API may be accessed with an API key **AND** OAuth 2.0 **OR** with basic authentication: 134 | 135 | ```yaml 136 | security: # apiKey AND oauth2 OR basic 137 | - apiKey: [] 138 | oauth2: 139 | - read 140 | - write 141 | - basic: [] 142 | ``` 143 | 144 | ## Security Requirement Scopes or Roles 145 | 146 | When defining an OAuth 2.0 or OpenID Connect [Security Requirement Object](/openapi/security#security-requirement-object) for an operation, the `{securitySchemeName}` field should contain a list of scopes or roles required for the security scheme. 147 | 148 | For example, the following security requirement object requires the `read` and `write` scopes for the `oauth2` security scheme: 149 | 150 | ```yaml 151 | paths: 152 | /drinks: 153 | get: 154 | operationId: listDrinks 155 | summary: Get a list of drinks 156 | # Operation requires read and write scopes 157 | security: 158 | - oauth2: 159 | - read 160 | - write 161 | # ... 162 | ``` 163 | -------------------------------------------------------------------------------- /reference/security/security-schemes.md: -------------------------------------------------------------------------------- 1 | # Security Scheme Objects in OpenAPI 2 | 3 | Security scheme objects are defined in the [Components Object](../components.md) under the `securitySchemes` field. Each security scheme object has a unique key. [Security Requirement Objects](../security.md#security-requirement-object) elsewhere in the document reference security scheme objects by their keys. 4 | 5 | The following example requires a basic authentication scheme to access the `/drinks` endpoint: 6 | 7 | ```yaml 8 | paths: 9 | /drinks: 10 | get: 11 | security: 12 | - MyScheme17: [] 13 | components: 14 | securitySchemes: 15 | MyScheme17: 16 | type: http 17 | scheme: basic 18 | ``` 19 | 20 | The `type` field is the overall category of authentication. The value of `type` determines the other fields the security object needs. 21 | 22 | To decide which authentication type to choose, see our article [OpenAPI Tips - How to Handle Auth](https://www.speakeasyapi.dev/post/openapi-tips-auth). 23 | 24 | ## Supported Authentication Types 25 | 26 | The following authentication types are supported in the OpenAPI Specification: 27 | 28 | - [API Key](./security-schemes/security-api-key.md) 29 | - [Basic HTTP](./security-schemes/security-basic.md) 30 | - [Bearer Token](./security-schemes/security-bearer.md) 31 | - [OAuth 2.0](./security-schemes/security-oauth2.md) 32 | - [OpenID Connect](./security-schemes/security-openid.md) 33 | - Digest 34 | - Mutual TLS 35 | 36 | ## Example Security Scheme Schema 37 | 38 | Below is an example security schemes object with every possible field besides extensions. 39 | 40 | ```yaml 41 | components: 42 | securitySchemes: 43 | # apiKey ------------ 44 | auth1: 45 | description: Recommended authenticator 46 | type: apiKey 47 | in: query 48 | name: key 49 | 50 | auth2: 51 | type: apiKey 52 | in: header 53 | name: X-API-Key 54 | 55 | auth3: 56 | type: apiKey 57 | in: cookie 58 | name: key 59 | 60 | # http ------------ 61 | auth4: 62 | type: http 63 | scheme: basic 64 | 65 | auth5: 66 | type: http 67 | scheme: bearer 68 | bearerFormat: JWT 69 | 70 | auth6: 71 | type: http 72 | scheme: digest # not supported by Speakeasy 73 | 74 | # mutualTLS ------------ 75 | auth7: 76 | type: mutualTLS # not supported by Speakeasy 77 | 78 | # openIdConnect ------------ 79 | auth8: 80 | type: openIdConnect 81 | openIdConnectUrl: https://example.com/openidconfig.json 82 | 83 | # oauth2 ------------ 84 | auth9: 85 | type: oauth2 86 | flows: 87 | authorizationCode: 88 | scopes: 89 | read: Grants read access 90 | write: Grants write access 91 | authorizationUrl: https://test.com/oauth/authorize 92 | tokenUrl: https://test.com/oauth/token 93 | refreshUrl: https://test.com/oauth/refresh 94 | clientCredentials: 95 | scopes: 96 | read: Grants read access 97 | write: Grants write access 98 | tokenUrl: https://test.com/oauth/token 99 | refreshUrl: https://test.com/oauth/refresh 100 | implicit: 101 | scopes: 102 | read: Grants read access 103 | write: Grants write access 104 | authorizationUrl: https://test.com/oauth/authorize 105 | refreshUrl: https://test.com/oauth/refresh 106 | password: 107 | scopes: 108 | read: Grants read access 109 | write: Grants write access 110 | tokenUrl: https://test.com/oauth/token 111 | refreshUrl: https://test.com/oauth/refresh 112 | ``` 113 | -------------------------------------------------------------------------------- /reference/security/security-schemes/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "security-api-key": "API Key Security", 3 | "security-basic": "Basic Security", 4 | "security-bearer": "Bearer Security", 5 | "security-oauth2": "OAuth2.0 Security", 6 | "security-openid": "OpenID Connect Security" 7 | } 8 | -------------------------------------------------------------------------------- /reference/security/security-schemes/security-api-key.md: -------------------------------------------------------------------------------- 1 | # API Key Security Scheme in OpenAPI 2 | 3 | An API Key security scheme is the most common form of authentication for machine-to-machine APIs and supports passing a pre-shared secret in several ways. The secret can be passed either via the Authorization header (or another custom header), as a query parameter, or via a cookie. 4 | 5 | While this is probably the most commonly used mechanism, it is generally one of the least secure. This is especially true if the key is passed outside of headers or cookies (that is, via query params, as various logging mechanisms normally store query param information). 6 | 7 | The biggest security flaw is that most pre-shared secrets are long-lived and if intercepted, can be used until they are either revoked or expire (generally in months or years). This risk is normally tolerated for machine-to-machine applications as the chance of interception (especially when using private VPCs/TLS and other mechanisms) is relatively low compared to a key from a user’s device traveling on a public network. 8 | 9 | The fields for an API Key security scheme are as follows: 10 | 11 | | Field | Type | Required | Description | 12 | | ------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 13 | | `type` | String | ✅ | `apiKey` | 14 | | `description` | String | | Human-readable information. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 15 | | `in` | String | ✅ | The location of the API key in the request. Valid values are `query`, `header`, or `cookie`. | 16 | | `name` | String | ✅ | The name of the key parameter in the location. | 17 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the security scheme object to be used by tooling and vendors. | 18 | 19 | ```yaml 20 | components: 21 | securitySchemes: 22 | api_key: 23 | type: apiKey 24 | name: api_key 25 | in: header 26 | security: 27 | - api_key: [] 28 | ``` 29 | -------------------------------------------------------------------------------- /reference/security/security-schemes/security-basic.md: -------------------------------------------------------------------------------- 1 | # Basic Security Scheme in OpenAPI 2 | 3 | A Basic security scheme is a simple authentication mechanism baked into the HTTP protocol that supports sending an Authorization header containing an encoded username and password. 4 | 5 | A Basic security scheme can be a relatively simple mechanism to get started with, but risks leaking easy-to-decode passwords if used incorrectly. 6 | 7 | Basic security also shares the downside of API keys in that the password is generally long-lived and if intercepted, can be used until it is either revoked or expires. 8 | 9 | The fields for a Basic security scheme are as follows: 10 | 11 | | Field | Type | Required | Description | 12 | | ------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 13 | | `type` | String | ✅ | `http` | 14 | | `description` | String | | Human-readable information. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 15 | | `scheme` | String | ✅ | `basic` | 16 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the security scheme object to be used by tooling and vendors. | 17 | 18 | ```yaml 19 | components: 20 | securitySchemes: 21 | auth: 22 | type: http 23 | scheme: basic 24 | security: 25 | - auth: [] 26 | ``` 27 | -------------------------------------------------------------------------------- /reference/security/security-schemes/security-bearer.md: -------------------------------------------------------------------------------- 1 | # Bearer Security Scheme in OpenAPI 2 | 3 | The Bearer security scheme allows passing a token (most commonly a JWT) in the Authorization header. 4 | 5 | A Bearer security scheme is generally used for short-lived tokens granted to your API users through an additional login mechanism. Using a JWT allows for storing additional metadata within the token, which can be helpful for some use cases, such as storing scopes for permissions models. 6 | 7 | The fields for a Bearer security scheme are as follows: 8 | 9 | | Field | Type | Required | Description | 10 | | ------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 11 | | `type` | String | ✅ | `http` | 12 | | `description` | String | | Human-readable information. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 13 | | `scheme` | String | ✅ | `bearer` | 14 | | `bearerFormat` | String | | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. | 15 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the security scheme object to be used by tooling and vendors. | 16 | 17 | ```yaml 18 | components: 19 | securitySchemes: 20 | auth: 21 | type: http 22 | scheme: bearer 23 | bearerFormat: JWT 24 | security: 25 | - auth: [] 26 | ``` 27 | -------------------------------------------------------------------------------- /reference/security/security-schemes/security-oauth2.md: -------------------------------------------------------------------------------- 1 | # OAuth 2.0 Security Scheme in OpenAPI 2 | 3 | OAuth 2.0 is a popular open authentication mechanism that supports an authentication flow allowing servers to authenticate on behalf of a user or organization. 4 | 5 | While more generally used for authenticating clients and end-users, it is sometimes used in machine-to-machine applications, but is less popular than other security schemes due to the added complexity of the authentication flows. 6 | 7 | OAuth 2.0 is considered more secure than other mechanisms due to its granted privileges through short-lived tokens that limit damage from intercepted tokens. 8 | 9 | The OAuth 2.0 protocol defines multiple ways of building a request against the `tokenUrl` endpoint. 10 | 11 | ## OAuth 2.0 Security Scheme Object 12 | 13 | The fields for an OAuth 2.0 security scheme are as follows: 14 | 15 | | Field | Type | Required | Description | 16 | | ------------- | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 17 | | `type` | String | ✅ | `oauth2` | 18 | | `description` | String | | Human-readable information. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 19 | | `flows` | Map[{key}, [OAuth Flow Object](#oauth-flow-object)] | ✅ | An object containing configuration for the available OAuth 2.0 flows. Valid keys are `implicit`, `password`, `clientCredentials`, and `authorizationCode`. | 20 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the security scheme object to be used by tooling and vendors. | 21 | 22 | Below is an example of an OAuth 2.0 security scheme using the `clientCredentials` flow: 23 | 24 | ```yaml 25 | components: 26 | securitySchemes: 27 | clientCredentials: 28 | type: oauth2 29 | flows: 30 | clientCredentials: 31 | tokenUrl: https://speakeasy.bar/oauth2/token/ 32 | scopes: {} 33 | security: 34 | - clientCredentials: [] 35 | ``` 36 | 37 | ## OAuth Flow Object 38 | 39 | The value of the `flows` object is a map of OAuth 2.0 flow objects. 40 | 41 | The four supported OAuth 2.0 flows are: 42 | 43 | - `implicit` - [Implicit Flow Object](#implicit-flow-object) 44 | - `password` - [Password Flow Object](#password-flow-object) 45 | - `clientCredentials` (previously, `application` in OpenAPI 2.0) - [Client Credentials Flow Object](#client-credentials-flow-object) 46 | - `authorizationCode` (previously, `accessCode` in OpenAPI 2.0) - [Authorization Code Flow Object](#authorization-code-flow-object) 47 | 48 | Each flow object has its own configuration parameters, as described below. 49 | 50 | ### Implicit Flow Object 51 | 52 | The Implicit flow is generally used for single-page applications that can't keep a client secret as all the application code is available to the user. 53 | 54 | | Field | Type | Required | Description | 55 | | ------------------ | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 56 | | `authorizationUrl` | String | ✅ | The authorization URL to be used for this flow. | 57 | | `refreshUrl` | String | | The URL to be used for refreshing the token. No refresh URL means the token is not refreshable. | 58 | | `scopes` | Map[String, String] | ✅ | The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object. | 59 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification. | 60 | 61 | The example below shows an OAuth 2.0 security scheme using the `implicit` flow: 62 | 63 | ```yaml 64 | components: 65 | securitySchemes: 66 | implicit: 67 | type: oauth2 68 | flows: 69 | implicit: 70 | authorizationUrl: https://speakeasy.bar/oauth2/authorize/ 71 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 72 | scopes: 73 | read: Grants read access 74 | write: Grants write access 75 | ``` 76 | 77 | ### Password Flow Object 78 | 79 | The Password flow is generally used for trusted first-party clients that can securely store the client secret. 80 | 81 | | Field | Type | Required | Description | 82 | | ------------ | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 83 | | `tokenUrl` | String | ✅ | The token URL to be used for this flow. | 84 | | `refreshUrl` | String | | The URL to be used for refreshing the token. No refresh URL means the token is not refreshable. | 85 | | `scopes` | Map[String, String] | ✅ | The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object. | 86 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification. | 87 | 88 | The example below shows an OAuth 2.0 security scheme using the `password` flow: 89 | 90 | ```yaml 91 | components: 92 | securitySchemes: 93 | password: 94 | type: oauth2 95 | flows: 96 | password: 97 | tokenUrl: https://speakeasy.bar/oauth2/token/ 98 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 99 | scopes: 100 | read: Grants read access 101 | write: Grants write access 102 | ``` 103 | 104 | ### Client Credentials Flow Object 105 | 106 | The Client Credentials flow is generally used for machine-to-machine communication where a specific user's permission is not required. 107 | 108 | | Field | Type | Required | Description | 109 | | ------------ | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 110 | | `tokenUrl` | String | ✅ | The token URL to be used for this flow. | 111 | | `refreshUrl` | String | | The URL to be used for refreshing the token. No refresh URL means the token is not refreshable. | 112 | | `scopes` | Map[String, String] | ✅ | The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object. | 113 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification. | 114 | 115 | The example below shows an OAuth 2.0 security scheme using the `clientCredentials` flow: 116 | 117 | ```yaml 118 | components: 119 | securitySchemes: 120 | clientCredentials: 121 | type: oauth2 122 | flows: 123 | clientCredentials: 124 | tokenUrl: https://speakeasy.bar/oauth2/token/ 125 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 126 | scopes: 127 | read: Grants read access 128 | write: Grants write access 129 | ``` 130 | 131 | ### Authorization Code Flow Object 132 | 133 | The Authorization Code flow is generally used for server-side applications where the client secret can be securely stored. 134 | 135 | | Field | Type | Required | Description | 136 | | ------------------ | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 137 | | `authorizationUrl` | String | ✅ | The authorization URL to be used for this flow. | 138 | | `tokenUrl` | String | ✅ | The token URL to be used for this flow. | 139 | | `refreshUrl` | String | | The URL to be used for refreshing the token. No refresh URL means the token is not refreshable. | 140 | | `scopes` | Map[String, String] | ✅ | The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object. | 141 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification. | 142 | 143 | The example below shows an OAuth 2.0 security scheme using the `authorizationCode` flow: 144 | 145 | ```yaml 146 | components: 147 | securitySchemes: 148 | authorizationCode: 149 | type: oauth2 150 | flows: 151 | authorizationCode: 152 | authorizationUrl: https://speakeasy.bar/oauth2/authorize/ 153 | tokenUrl: https://speakeasy.bar/oauth2/token/ 154 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 155 | scopes: 156 | read: Grants read access 157 | write: Grants write access 158 | ``` 159 | 160 | ## OAuth 2.0 Security Scheme With Multiple Flows 161 | 162 | You can define an OAuth 2.0 security scheme with multiple flows by specifying each flow in the `flows` object. 163 | 164 | The example below shows an OAuth 2.0 security scheme using the `authorizationCode` and `clientCredentials` flows: 165 | 166 | ```yaml 167 | components: 168 | securitySchemes: 169 | oauth2: 170 | type: oauth2 171 | flows: 172 | authorizationCode: 173 | authorizationUrl: https://speakeasy.bar/oauth2/authorize/ 174 | tokenUrl: https://speakeasy.bar/oauth2/token/ 175 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 176 | scopes: 177 | read: Grants read access 178 | write: Grants write access 179 | clientCredentials: 180 | tokenUrl: https://speakeasy.bar/oauth2/token/ 181 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 182 | scopes: 183 | read: Grants read access 184 | write: Grants write access 185 | security: 186 | - oauth2: [] 187 | ``` 188 | 189 | ## Scopes in OAuth 2.0 190 | 191 | Scopes are used to define the permissions that a client has when accessing a resource. The scopes are defined in the `scopes` object of the OAuth flow object. 192 | 193 | The scopes required for a specific operation are defined in the `security` object of the operation. 194 | 195 | The example below shows an OAuth 2.0 security scheme with scopes: 196 | 197 | ```yaml 198 | components: 199 | securitySchemes: 200 | oauth2: 201 | type: oauth2 202 | flows: 203 | authorizationCode: 204 | authorizationUrl: https://speakeasy.bar/oauth2/authorize/ 205 | tokenUrl: https://speakeasy.bar/oauth2/token/ 206 | refreshUrl: https://speakeasy.bar/oauth2/refresh/ 207 | scopes: 208 | read: Grants read access 209 | write: Grants write access 210 | paths: 211 | /drinks: 212 | get: 213 | operationId: listDrinks 214 | summary: Get a list of drinks 215 | # Operation requires read scope 216 | security: 217 | - oauth2: 218 | - read 219 | ``` 220 | -------------------------------------------------------------------------------- /reference/security/security-schemes/security-openid.md: -------------------------------------------------------------------------------- 1 | # OpenID Connect Security Scheme in OpenAPI 2 | 3 | The OpenID Connect security scheme allows for the discovery of configuration values for an OpenID Connect provider. This is generally used for authentication mechanisms based on the OpenID Connect protocol. 4 | 5 | The fields for an OpenID Connect security scheme are as follows: 6 | 7 | | Field | Type | Required | Description | 8 | | ------------------ | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 9 | | `type` | String | ✅ | `openIdConnect` | 10 | | `description` | String | | Human-readable information. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 11 | | `openIdConnectUrl` | String | ✅ | The URL must point to a JSON OpenID Connect Discovery document. | 12 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the security scheme object to be used by tooling and vendors. | 13 | 14 | The following is an example of an OpenID Connect security scheme: 15 | 16 | ```yaml 17 | components: 18 | securitySchemes: 19 | openid_connect: 20 | type: openIdConnect 21 | openIdConnectUrl: https://example.com/.well-known/openid-configuration 22 | security: 23 | - openid_connect: 24 | - read 25 | - write 26 | paths: 27 | /drinks: 28 | get: 29 | operationId: listDrinks 30 | summary: Get a list of drinks 31 | # Operation requires read scope 32 | security: 33 | - openid_connect: 34 | - read:drink 35 | post: 36 | operationId: createDrink 37 | summary: Create a new drink 38 | # Operation requires write scope 39 | security: 40 | - openid_connect: 41 | - write:drink 42 | ``` 43 | 44 | ## Scopes in OpenID Connect 45 | 46 | When specifying the required security schemes for an operation, you can also specify the required scopes for that operation. This is done by adding the required scopes as an array of strings to the security scheme object. 47 | 48 | In the example above, the `listDrinks` operation requires the `read:drink` scope, and the `createDrink` operation requires the `write:drink` scope. This allows for fine-grained control over the permissions required to access different parts of the API. 49 | -------------------------------------------------------------------------------- /reference/servers.md: -------------------------------------------------------------------------------- 1 | # Servers 2 | 3 | A list of [Server Objects](/openapi/servers) that either the entire API or a specific path or operation is available on. Servers can be defined at the [Document](/openapi#openapi-document-structure) level, the [Path](/openapi/paths) level, or the [Operation](/openapi/paths/operations) level. 4 | 5 | Servers are optional in the OpenAPI specification. If not provided, the default URL is assumed to be `/`, a path relative to where the OpenAPI document is hosted. 6 | 7 | Generally, the first server in the list is considered to be the default server to use, with logic to select other servers to use left up to tooling or the API consumer. 8 | 9 | Example: 10 | 11 | ```yaml 12 | servers: 13 | - url: https://speakeasy.bar 14 | description: The production server 15 | - url: https://staging.speakeasy.bar 16 | description: The staging server 17 | ``` 18 | 19 | If a list of servers is provided at the `paths` level, the servers will override any servers provided at the document level. If a list of servers is provided at the `operation` level, the servers will override any servers provided at the `paths` and document levels. 20 | 21 | ## Server Object 22 | 23 | A Server Object describes a single server that is available for the API. 24 | 25 | | Field | Type | Required | Description | 26 | | ------------- | :---------------------------------------------------: | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 27 | | `url` | String | ✅ | A URL to the server. This can be an absolute URL or a relative URL to the hosted location of the OpenAPI document. The URL also supports variable substitutions via [Templating](/openapi/servers/server-variables). | 28 | | `description` | String | | A description of the server. [CommonMark syntax](https://spec.commonmark.org/) can be used to provide a rich description. | 29 | | `variables` | [Server Variables](/openapi/servers/server-variables) | | A map of variable names to [Server Variable Objects](/openapi/servers/server-variables#server-variable-object) that can be used for variable substitution via [Templating](/openapi/servers/server-variables). | 30 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the Server Object ([for example, `x-speakeasy-server-id`](/docs/customize-sdks/servers#managing-multiple-servers-with-ids) that allows IDs to be assigned to each server for easier selection via Speakeasy SDKs) that can be used by tooling and vendors. | 31 | 32 | If the URL is an absolute path, it **_must_** conform to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) (`schema://host{:port}{/path}`) and not include the query string, and **_must_** be URL encoded (except for the templating delimiters `{}` if not part of the URL). 33 | 34 | The URL can also be a relative path to where the OpenAPI document is hosted (`/api`). For a document hosted at `https://speakeasy.bar/openapi.yaml`, the resulting URL will be `https://speakeasy.bar/api`. 35 | 36 | The URL may also contain fragments (for example, `https://speakeasy.bar/drinks#mocktails`) allowing for repeated URLs with different fragments to be defined in the same document and the definition of multiple operations with the same URL and HTTP method but different operation definitions. 37 | 38 | For example, the below document is not valid as it defines two operations with the same URL and HTTP method: 39 | 40 | ```yaml 41 | paths: 42 | /drinks: 43 | get: 44 | operationId: listCocktails 45 | summary: Get a list of cocktails 46 | parameters: 47 | - name: type 48 | in: query 49 | schema: 50 | type: string 51 | const: cocktail 52 | responses: 53 | "200": 54 | description: A list of cocktails 55 | content: 56 | application/json: 57 | schema: 58 | type: array 59 | items: 60 | $ref: "#/components/schemas/Cocktail" 61 | /drinks: 62 | get: 63 | operationId: listMocktails 64 | summary: Get a list of mocktails 65 | parameters: 66 | - name: type 67 | in: query 68 | schema: 69 | type: string 70 | const: mocktail 71 | responses: 72 | "200": 73 | description: A list of mocktails 74 | content: 75 | application/json: 76 | schema: 77 | type: array 78 | items: 79 | $ref: "#/components/schemas/Mocktail" 80 | ``` 81 | 82 | However, the below document is valid as it defines two operations with the same URL and HTTP method but different fragments, making the paths unique: 83 | 84 | ```yaml 85 | paths: 86 | /drinks#cocktails: 87 | get: 88 | operationId: listCocktails 89 | summary: Get a list of cocktails 90 | parameters: 91 | - name: type 92 | in: query 93 | schema: 94 | type: string 95 | const: cocktail 96 | responses: 97 | "200": 98 | description: A list of cocktails 99 | content: 100 | application/json: 101 | schema: 102 | type: array 103 | items: 104 | $ref: "#/components/schemas/Cocktail" 105 | /drinks#mocktails: 106 | get: 107 | operationId: listMocktails 108 | summary: Get a list of mocktails 109 | parameters: 110 | - name: type 111 | in: query 112 | schema: 113 | type: string 114 | const: mocktail 115 | responses: 116 | "200": 117 | description: A list of mocktails 118 | content: 119 | application/json: 120 | schema: 121 | type: array 122 | items: 123 | $ref: "#/components/schemas/Mocktail" 124 | ``` 125 | 126 | **Note:** The above API can also be achieved using [`oneOf`](/openapi/schemas/objects/polymorphism) in a single operation definition, but depending on the use case, this may not be desirable. 127 | -------------------------------------------------------------------------------- /reference/servers/server-variables.md: -------------------------------------------------------------------------------- 1 | # Server Variables 2 | 3 | Server variables are a map of variable names (string) to [Server Variable Objects](/openapi/servers/server-variables#server-variable-object) that can be used for variable substitution via Templating. 4 | 5 | ## Server Variable Object 6 | 7 | A Server Variable Object describes a single variable that is optionally part of the URL in a [Server Object](/openapi/servers). The value of a variable can be any arbitrary string value unless a list of allowed values is provided via the `enum` field. 8 | 9 | | Field | Type | Required | Description | 10 | | ------------- | :-----------------------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------- | 11 | | `description` | String | | A description of the variable. [CommonMark syntax](https://spec.commonmark.org/) can be used to provide a rich description. | 12 | | `default` | String | ✅ | The default value of the variable. A variable is always of type _string_. If `enum` is provided this **_must_** be one of the values in the `enum` list. | 13 | | `enum` | List\ | | A list of allowed string values for the variable. | 14 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the Server Variable Object that can be used by tooling and vendors. | 15 | 16 | Example: 17 | 18 | ```yaml 19 | servers: 20 | - url: https://{organization}.{environment}.speakeasy.bar 21 | description: A per-organization and per-environment API 22 | variables: 23 | organization: 24 | description: The organization name. Defaults to a generic organization. 25 | default: api 26 | environment: 27 | description: The environment name. Defaults to the production environment. 28 | default: prod 29 | enum: 30 | - prod 31 | - staging 32 | - dev 33 | ``` 34 | 35 | Any variable delimited by `{}` in the `url` field declares a part of the URL that **_must_** be replaced with a value and references a variable that **_must_** be defined in the `variables` map. It is the API consumer's responsibility to replace these variables (including the delimiters) with values to create a valid URL before making a request to the API. The defined `default` should be used if no other value is provided. -------------------------------------------------------------------------------- /reference/tags.md: -------------------------------------------------------------------------------- 1 | # Tags 2 | 3 | The document-level `tags` field contains a list of [tag](/openapi/tags#tag-object) definitions that may be used to categorize or group operations in the API. Tags can be referenced by [operations](/openapi/paths/operations) via the operations-level `tags` field. 4 | 5 | Tag definitions at the document level are optional, even if an undefined tag is referenced in an [operation](/openapi/paths/operations), but it is recommended that all tags used are defined here to provide useful documentation and intent for the tags. 6 | 7 | Tag names **_must_** be unique in the document. 8 | 9 | Example: 10 | 11 | ```yaml 12 | tags: 13 | - name: drinks 14 | description: The drinks endpoints. 15 | - name: authentication 16 | description: The authentication endpoints. 17 | ``` 18 | 19 | ## Tag Object 20 | 21 | A Tag Object defines a single tag that can be used to categorize or group operations in the API. 22 | 23 | | Field | Type | Required | Description | 24 | | -------------- | :-------------------------------------------------------------: | :------: | --------------------------------------------------------------------------------------------------------------------------- | 25 | | `name` | String | ✅ | The name of the tag. **_Must_** be unique in the document. | 26 | | `description` | String | | A description of the tag. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description. | 27 | | `externalDocs` | [External Documentation Object](/openapi/external-documentation) | | Additional external documentation for this tag. | 28 | | `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields can be added to the tag object that can be used by tooling and vendors. | 29 | 30 | ## Multiple Namespaces 31 | 32 | If you want to add a method to multiple namespaces, list multiple values in tags. It accepts an array of values: 33 | 34 | ```yaml 35 | paths: 36 | /drinks: 37 | get: 38 | operationId: listDrinks 39 | tags: 40 | - drinks 41 | - beverages 42 | ``` -------------------------------------------------------------------------------- /reference/webhooks.md: -------------------------------------------------------------------------------- 1 | # Webhooks 2 | 3 | **(Available in OpenAPI 3.1.x ONLY)** 4 | 5 | `webhooks` are a mechanism that allows an API to send real-time data to a user as soon as an event occurs (without requiring the user to take any action). The user simply needs to subscribe to the event stream and provide a URL to start receiving data. 6 | 7 | The `webhooks` element has identical syntax to the `paths` element. Both are lists of [Path Item Objects](/openapi/paths#path-item-object). (This makes sense if you consider that a webhook is like a reverse path: Just as paths describe endpoints on the server's API, webhooks describe endpoints on the user's API.) 8 | 9 | This means a webhook has all the following path properties available to it: `$ref`, `summary`, `description`, `get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace`, `servers`, and `parameters`. 10 | 11 | For example: 12 | 13 | ```yaml 14 | webhooks: 15 | stockUpdate: 16 | post: 17 | summary: Receive stock updates. 18 | description: Receive stock updates from the bar, this will be called whenever the stock levels of a drink or ingredient change. 19 | tags: 20 | - drinks 21 | - ingredients 22 | requestBody: 23 | required: true 24 | content: 25 | application/json: 26 | schema: 27 | type: object 28 | properties: 29 | drink: 30 | $ref: "#/components/schemas/Drink" 31 | ingredient: 32 | $ref: "#/components/schemas/Ingredient" 33 | responses: 34 | "200": 35 | description: The stock update was received successfully. 36 | "5XX": 37 | $ref: "#/components/responses/APIError" 38 | default: 39 | $ref: "#/components/responses/UnknownError" 40 | ``` 41 | 42 | ## The AsyncAPI Standard? 43 | 44 | OpenAPI is a general-purpose API specification that can be used for asynchronous APIs, but it is not necessarily optimized for them. If you find that OpenAPI is insufficient for your use case, you should check out [AsyncAPI](https://www.asyncapi.com/). Just be aware that AsyncAPI is still in the early stages of development and is not yet widely supported by the tooling ecosystem. --------------------------------------------------------------------------------