OpenAPI

https://learn.openapis.org
Admin
OpenAPI is the most broadly adopted industry standard for describing HTTP-based APIs in a...
Tokens:31,316
Snippets:364
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Media Type with Multiple Examples

Source: https://learn.openapis.org/specification/docs

The `examples` field in a Media Type Object allows multiple named examples. Each example can have a summary and description, with the actual value provided in the `value` field. All examples must match the media type's schema.

```yaml
responses:
  "400":
    description: The provided parameters are incorrect
    content:
      text/html: # This is a Media Type Object
        schema:
          type: string
        examples:
          illegalCoordinates:
            value: "Illegal coordinates."
          notEmpty:
            value: "Square is not empty."
          invalidMark:
            value: "Invalid Mark (X or O)."
```

--------------------------------

### Change Schema Example to Examples

Source: https://learn.openapis.org/upgrading/v3.0-to-v3.1

Convert the singular `example` keyword to the plural `examples` array in OpenAPI 3.1 for schema objects. This allows for multiple examples.

```yaml
# OpenAPI 3.0
type: string
example: fedora
```

```yaml
# OpenAPI 3.1
type: string
examples:
 - fedora
```

```yaml
type: string
examples:
 - fedora
 - ubuntu
```

--------------------------------

### YAML Data Structure Example

Source: https://learn.openapis.org/specification/structure

Demonstrates equivalent data structure in YAML, highlighting its reliance on indentation and use of hyphens for array items. YAML supports comments starting with '#'.

```yaml
# Anything after a hash sign is a comment
anObject:
  aNumber: 42
  aString: This is a string
  aBoolean: true
  nothing: null
  arrayOfNumbers:
    - 1
    - 2
    - 3
```

--------------------------------

### Minimal OpenAPI Description Example

Source: https://learn.openapis.org/specification/structure

This example shows the most basic structure of an OpenAPI Description. It includes the required 'openapi' version, 'info' object with title and version, and an empty 'paths' object as no endpoints are defined.

```yaml
openapi: 3.1.0
info:
  title: A minimal OpenAPI Description
  version: 0.0.1
paths: {} # No endpoints defined

```

--------------------------------

### Path Parameter Example

Source: https://learn.openapis.org/specification/parameters

Example of defining a path parameter for an operation.

```APIDOC
## Path Parameter Example

### Description
Demonstrates how to define a parameter that is part of the operation's URL path.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the user.

### Request Example
(No specific request body or query parameters shown in this example)

### Response
(Response details not specified in this example)
```

--------------------------------

### Schema with Single Example

Source: https://learn.openapis.org/specification/docs

Use the `example` field within a Schema Object to provide a single sample value. This value must conform to the schema's type and constraints.

```yaml
schema:
  coordinate:
    type: integer
    minimum: 1
    maximum: 3
    example: 1
```

--------------------------------

### Complete Enhanced Tags Example (OpenAPI 3.2)

Source: https://learn.openapis.org/specification/tags

This comprehensive example demonstrates the use of 'summary', 'parent', and 'kind' fields for advanced tag organization in OpenAPI 3.2.

```yaml
openapi: 3.2.0
info:
  title: Bakery API
  version: 2.0.0

tags:
  # Main navigation categories
  - name: products
    summary: Products
    description: All bakery product operations
    kind: nav

  - name: orders
    summary: Orders
    description: Order management and tracking
    kind: nav

  # Product subcategories
  - name: cakes
    summary: Cakes
    description: Custom cakes and layer cakes
    parent: products
    kind: nav

  - name: breads
    summary: Breads
    description: Artisan breads and rolls
    parent: products
    kind: nav

  # Special categories
  - name: seasonal
    summary: Seasonal
    description: Limited-time seasonal offerings
    kind: badge
    externalDocs:
      description: Seasonal menu planning
      url: https://docs.bakery.com/seasonal

paths:
  /cakes:
    get:
      tags: [cakes]
      summary: List available cakes

  /cakes/seasonal:
    get:
      tags: [cakes, seasonal]
      summary: List seasonal cake offerings

  /orders/wholesale:
    post:
      tags: [orders, wholesale]
      summary: Create wholesale order


```

--------------------------------

### Query Parameter Example

Source: https://learn.openapis.org/specification/parameters

Example of defining a query parameter for an operation.

```APIDOC
## Query Parameter Example

### Description
Demonstrates how to define a parameter that is appended to the query string of the operation's URL.

### Method
GET

### Endpoint
/users?id=1234

### Parameters
#### Query Parameters
- **id** (string) - Optional - The identifier to filter users.

### Request Example
(No specific request body or path parameters shown in this example)

### Response
(Response details not specified in this example)
```

--------------------------------

### OpenAPI Parameter Description Example

Source: https://learn.openapis.org/specification/docs

Use the `description` field to provide detailed information about a parameter's purpose and value effects. This example shows a schema for an integer parameter with minimum, maximum, and a multi-line description.

```yaml
paths:
  /audio/volume:
    put:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: integer
              minimum: 0
              maximum: 11
              description:
                Current volume for all audio output.
                0 means no audio output (mute). 10 is the maximum value. 11 enables
                the overdrive system (danger!).
                When set to 0 all other audio settings have no effect.
              ...

```

--------------------------------

### Path Parameter Example

Source: https://learn.openapis.org/specification/parameters

Define a path parameter named 'id' for the '/users/{id}' endpoint. Path parameters must be marked as required.

```yaml
paths:
  /users/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true

```

--------------------------------

### Complete Example: Referencing Components

Source: https://learn.openapis.org/specification/components

Illustrates how to define components and reference them within the same document, including using a schema component within parameter definitions and referencing parameters from a path.

```yaml
components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
    columnParam:
      name: column
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
paths:
  /board/{row}/{column}:
    parameters:
      - $ref: "#/components/parameters/rowParam"
      - $ref: "#/components/parameters/columnParam"

```

--------------------------------

### Querystring Parameter Example (OpenAPI 3.2+)

Source: https://learn.openapis.org/specification/parameters

Example of using the 'querystring' parameter for complex query string structures.

```APIDOC
## Querystring Parameter Example (OpenAPI 3.2+)

### Description
Shows how to define the entire query string as a single parameter with a complex schema.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **advancedQuery** (object) - Required - Defines the structure for complex query parameters.
  - **filters** (object) - Optional - Filtering criteria.
  - **sorting** (array of strings) - Optional - Sorting preferences.

### Request Example
```yaml
parameters:
  - name: advancedQuery
    in: querystring
    content:
      application/x-www-form-urlencoded:
        schema:
          type: object
          properties:
            filters:
              type: object
            sorting:
              type: array
              items:
                type: string
```

### Response
(Response details not specified in this example)
```

--------------------------------

### Apply Segregated OAuth 2.0 Security Schemes to Operations

Source: https://learn.openapis.org/specification/security

This example shows how to apply the segregated OAuth 2.0 security schemes (`app2AppOauth` and `user2AppOauth`) to specific API operations. The `/board` GET operation uses `app2AppOauth` with `board:read` scope, while the `/board/{row}/{column}` PUT operation uses `user2AppOauth` with both `board:read` and `board:write` scopes.

```yaml
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0

paths:
  /board:
    get:
      security:
        - app2AppOauth:
          - board:read
      ...
  /board/{row}/{column}:
    put:
      security:
        - user2AppOauth:
          - board:read
          - board:write
      ...
```

--------------------------------

### Complete Tic Tac Toe Example Fragment

Source: https://learn.openapis.org/specification/paths

A fragment of the Tic Tac Toe OpenAPI Description, showcasing defined paths, operations, and responses. This example assumes prior understanding of the described objects.

```yaml
openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:
  # Whole board operations
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      responses:
        "200":
          description: "OK"
          content:
            ...


```

--------------------------------

### QUERY Method Example in OpenAPI 3.2+

Source: https://learn.openapis.org/specification/http-methods

Demonstrates the native support for the QUERY HTTP method in OpenAPI 3.2 and later, suitable for complex queries.

```yaml
# OpenAPI 3.2
paths:
  /products:
    query:
      summary: Advanced product search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                sort:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Search results
```

--------------------------------

### Server URL with Path Item

Source: https://learn.openapis.org/specification/servers

API endpoints are appended to the base server URL. This example shows how a '/users' path is combined with the server URL.

```yaml
servers:
- url: https://server.com/v1
paths:
  /users:
    get:
```

--------------------------------

### Query Parameter Example

Source: https://learn.openapis.org/specification/parameters

Define a query parameter named 'id' for the '/users' endpoint. This parameter will be appended to the URL's query string.

```yaml
paths:
  /users:
    get:
      parameters:
      - name: id
        in: query

```

--------------------------------

### Basic Tag Usage (OpenAPI 2.0+)

Source: https://learn.openapis.org/specification/tags

Tags have been available since OpenAPI 2.0 for basic operation grouping. This example shows how to define and apply tags to operations.

```yaml
openapi: 3.1.0
tags:
  - name: users
    description: User management operations
  - name: orders
    description: Order processing operations

paths:
  /users:
    get:
      tags: [users]
      summary: List users


```

--------------------------------

### Get Board Operation

Source: https://learn.openapis.org/specification/paths

Details of the GET operation for the /board endpoint, including its summary, description, and responses.

```APIDOC
## GET /board

### Description
Retrieves the current state of the board and the winner.

### Method
GET

### Endpoint
/board

### Responses
#### Success Response (200)
- **description**: "OK"
  **content**: [Details about the response payload would be here]
```

--------------------------------

### Multipart Mixed with prefixEncoding

Source: https://learn.openapis.org/specification/media-types

Example showing `prefixEncoding` for multipart/mixed to define content types for items based on their position.

```APIDOC
## POST /process/mixed

### Description
Processes a multipart/mixed request where items have predefined content types.

### Method
POST

### Endpoint
/process/mixed

### Parameters
#### Request Body
- **content** (object) - Describes the content of the request body.
  - **multipart/mixed** (object) - Specifies multipart/mixed content.
    - **prefixEncoding** (array) - Specifies encoding for items by position.
      - **contentType** (string) - The content type for the item at this position (e.g., 'application/json', 'text/html').

### Request Example
```yaml
content:
  multipart/mixed:
    prefixEncoding:
      - contentType: application/json
      - contentType: text/html
```
```

--------------------------------

### Multipart Form Data with itemEncoding

Source: https://learn.openapis.org/specification/media-types

Example demonstrating how to use `itemEncoding` for multipart/form-data to specify the content type for individual items.

```APIDOC
## POST /upload/files

### Description
Uploads multiple files with specified encoding for each item.

### Method
POST

### Endpoint
/upload/files

### Parameters
#### Request Body
- **content** (object) - Describes the content of the request body.
  - **multipart/form-data** (object) - Specifies multipart/form-data content.
    - **itemEncoding** (object) - Applies encoding to each item in the sequence.
      - **file** (object) - Encoding details for the 'file' part.
        - **contentType** (string) - The content type for the file part, e.g., 'application/octet-stream'.

### Request Example
```yaml
content:
  multipart/form-data:
    itemEncoding:
      file:
        contentType: application/octet-stream
```
```

--------------------------------

### Mixed JSON and YAML Syntax Example

Source: https://learn.openapis.org/specification/structure

Shows how JSON and YAML can be mixed within a single document, using YAML's indentation and array syntax with JSON's abbreviated array representation. This practice is generally not recommended.

```yaml
anObject:
  aString: This is a string
  arrayOfNumbers: [ 1, 2, 3 ] # Abbreviated array representation
```

--------------------------------

### Apply OAuth 2.0 Security Scheme Globally

Source: https://learn.openapis.org/specification/security

This example shows how to apply the `oauth2Profiles` security scheme globally to an API. It lists the required scopes for accessing the API's resources.

```yaml
openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
security:
  - oauth2Profiles:
    - board:read
    - board:write
paths:
  /board:
    get:
      security:
        - oauth2Profiles: []
```

--------------------------------

### Basic OpenAPI Structure with Paths

Source: https://learn.openapis.org/specification/paths

Defines the basic structure of an OpenAPI document including info and the paths object. Paths must start with a forward slash.

```yaml
openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:
  /board:
    ...


```

--------------------------------

### Request Body Object Example

Source: https://learn.openapis.org/specification/parameters

Illustrates a Request Body Object for an operation, specifying a JSON content type with an integer schema that has minimum and maximum constraints.

```APIDOC
## PUT /board

### Description
Updates a record on the database.

### Method
PUT

### Endpoint
/board

### Request Body
- **Required**: true
- **Content**: application/json
  - **Schema**: 
    - **type**: integer
    - **minimum**: 1
    - **maximum**: 100

### Response
#### Success Response (200)
- **Example**: A successful response structure would be detailed here if provided in the source.
```

--------------------------------

### Parameter with Schema Type and Constraints

Source: https://learn.openapis.org/specification/parameters

Specify the type and constraints for a query parameter using a Schema Object. This example defines an integer 'id' with minimum and maximum values.

```yaml
parameters:
- name: id
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100

```

--------------------------------

### Applying OAuth 2.0 Globally

Source: https://learn.openapis.org/specification/security

Shows how to apply an OAuth 2.0 security scheme globally to all operations within an API. This example uses the 'oauth2Profiles' defined previously and specifies required scopes.

```APIDOC
## Applying OAuth 2.0 Globally

### Description
Shows how to apply an OAuth 2.0 security scheme globally to all operations within an API. This example uses the 'oauth2Profiles' defined previously and specifies required scopes.

### OpenAPI Document Snippet
```yaml
openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
security:
  - oauth2Profiles:
    - board:read
    - board:write
paths:
  /board:
    get:
      security:
        - oauth2Profiles: []
```
```

--------------------------------

### JSON Data Structure Example

Source: https://learn.openapis.org/specification/structure

Illustrates a basic JSON object with various data types including numbers, strings, booleans, null, and arrays. JSON requires specific syntax like commas, curly braces, and double quotes.

```json
{
  "anObject": {
    "aNumber": 42,
    "aString": "This is a string",
    "aBoolean": true,
    "nothing": null,
    "arrayOfNumbers": [
      1,
      2,
      3
    ]
  }
}
```

--------------------------------

### Server-Sent Events with itemSchema

Source: https://learn.openapis.org/specification/media-types

Example of describing a Server-Sent Events stream using the `itemSchema` field to define the structure of each event.

```APIDOC
## GET /stream/updates

### Description
Retrieves a stream of updates.

### Method
GET

### Endpoint
/stream/updates

### Responses
#### Success Response (200)
- **content** (object) - Describes the content of the response.
  - **text/event-stream** (object) - Specifies Server-Sent Events.
    - **itemSchema** (object) - Describes the structure of each item in the stream.
      - **type** (string) - The schema type, expected to be 'object'.
      - **properties** (object) - Defines the properties of each item.
        - **id** (string) - The unique identifier for the update.
        - **data** (object) - The payload of the update.

### Response Example
```yaml
responses:
  '200':
    description: Stream of updates
    content:
      text/event-stream:
        itemSchema:
          type: object
          properties:
            id: { type: string }
            data: { type: object }
```
```

--------------------------------

### Path Item Object with Operations

Source: https://learn.openapis.org/specification/paths

Illustrates the Path Item Object, which describes HTTP operations like GET and PUT for a specific path. It can also contain common properties for all operations on that path.

```yaml
paths:
  /board:
    get:
      ...
    put:
      ...

```

--------------------------------

### Cookie Parameter with Object Schema (OpenAPI 3.2)

Source: https://learn.openapis.org/specification/parameters

This example demonstrates a cookie parameter named 'preferences' which is an object with 'theme' and 'language' string properties. This feature is new in OpenAPI 3.2.

```APIDOC
## GET /dashboard

### Description
Retrieves dashboard information.

### Method
GET

### Endpoint
/dashboard

### Parameters
#### Cookie Parameters
- **preferences** (object) - Required - User preferences for the dashboard.
  - **theme** (string) - Description of the theme preference.
  - **language** (string) - Description of the language preference.

### Response
#### Success Response (200)
- **Example**: A successful response structure would be detailed here if provided in the source.
```

--------------------------------

### Tic Tac Toe - Get Single Board Square

Source: https://learn.openapis.org/specification/parameters

Example of an operation to get the value of a single square on a Tic Tac Toe board, using path parameters for row and column.

```APIDOC
## GET /board/{row}/{column}

### Description
Get a single board square from the Tic Tac Toe game.

### Method
GET

### Endpoint
/board/{row}/{column}

### Parameters
#### Path Parameters
- **row** (integer) - Required - The row number of the square (1-3).
- **column** (integer) - Required - The column number of the square (1-3).

### Response
#### Success Response (200)
- **Example**: A successful response structure would be detailed here if provided in the source.
```

--------------------------------

### Basic Server Definitions

Source: https://learn.openapis.org/specification/servers

Define multiple base URLs for your API. Each server object requires a 'url' and can optionally include a 'description'.

```yaml
servers:
- url: https://europe.server.com/v1
  description: Server located in Germany.
- url: https://america.server.com/v1
  description: Server located in Atlanta, GA.
- url: https://asia.server.com/v1
  description: Server located in Shenzhen
```

--------------------------------

### Get the whole board

Source: https://learn.openapis.org/specification/content

Retrieves the current state of the Tic Tac Toe board and the winner of the game.

```APIDOC
## GET /board

### Description
Retrieves the current state of the board and the winner.

### Method
GET

### Endpoint
/board

### Response
#### Success Response (200)
- **winner** (string) - Winner of the game. `.` means nobody has won yet.
- **board** (array) - A 3x3 matrix representing the Tic Tac Toe board.

### Response Example
{
  "winner": ".",
  "board": [
    [".", ".", "."],
    [".", ".", "."],
    [".", ".", "."]
  ]
}
```

--------------------------------

### Add Description to Overlay Info

Source: https://learn.openapis.org/upgrading/overlay-v1.0-to-v1.1

Shows how to add a 'description' field to the 'info' section of an Overlay document for better documentation.

```yaml
overlay: 1.1.0
info:
  title: Overlay with description
  version: 1.0.0
  description: This overlay document has a long description thanks to the new field.
actions: []

```

--------------------------------

### Specify itemEncoding for Multipart Content

Source: https://learn.openapis.org/specification/media-types

The `itemEncoding` field applies encoding to each item within a multipart sequence. This example specifies `application/octet-stream` for file items.

```yaml
# OpenAPI 3.2
content:
  multipart/form-data:
    itemEncoding:
      file:
        contentType: application/octet-stream

```

--------------------------------

### CommonMark Code

Source: https://learn.openapis.org/specification/docs

Use backticks for inline code spans and triple backticks for fenced code blocks. This helps distinguish code examples within documentation.

```markdown
An inline `code span`.

A fenced code block
```

```

```

--------------------------------

### Standard HTTP Methods in OpenAPI

Source: https://learn.openapis.org/specification/http-methods

Describes how to use standard HTTP methods as operation keys in path items for all OpenAPI versions.

```yaml
paths:
  /users:
    get:      # Retrieve users
      summary: List users
      responses:
        '200':
          description: User list
    post:     # Create user
      summary: Create a new user
      responses:
        '201':
          description: User created
    put:      # Replace user collection
      summary: Replace all users
    delete:   # Delete users
      summary: Delete all users
    options:  # Get allowed methods
      summary: Get allowed methods for users endpoint
    head:     # Get headers only
      summary: Get user list headers
    patch:    # Update users
      summary: Update users
    trace:    # Diagnostic trace
      summary: Trace users endpoint
```

--------------------------------

### Specify prefixEncoding for Multipart Mixed Content

Source: https://learn.openapis.org/specification/media-types

The `prefixEncoding` field specifies encoding for items in a `multipart/mixed` sequence by their position. This example defines JSON and HTML content types.

```yaml
# OpenAPI 3.2
content:
  multipart/mixed:
    prefixEncoding:
      - contentType: application/json
      - contentType: text/html

```

--------------------------------

### Get delayed flights

Source: https://learn.openapis.org/examples/v3.2/3.2-tags-example.html

Retrieves information about delayed flights. This operation is associated with the 'delays' tag, which is highlighted as a 'badge' and links to external documentation for delay compensation policies.

```APIDOC
## GET /flights/delayed

### Description
Get delayed flights

### Method
GET

### Endpoint
/flights/delayed

### Tags
- delays

### External Docs
- **Description**: Delay compensation policies
- **URL**: https://docs.example.com/delay-policies
```

--------------------------------

### Migrate x-displayName to summary

Source: https://learn.openapis.org/upgrading/v3.1-to-v3.2

Replace the custom 'x-displayName' extension with the native 'summary' field for tag display. This improves compatibility and leverages built-in features.

```yaml
tags:
  - name: user-management
    description: User operations
    x-displayName: Users
```

```yaml
tags:
  - name: user-management
    summary: Users
    description: User operations
```

--------------------------------

### Applying Segregated OAuth 2.0 Security Requirements

Source: https://learn.openapis.org/specification/security

Demonstrates how to apply the segregated OAuth 2.0 security schemes ('app2AppOauth' and 'user2AppOauth') to specific API paths and operations, including the required scopes for each.

```APIDOC
## Applying Segregated OAuth 2.0 Security Requirements

### Description
Demonstrates how to apply the segregated OAuth 2.0 security schemes ('app2AppOauth' and 'user2AppOauth') to specific API paths and operations, including the required scopes for each.

### OpenAPI Document Snippet
```yaml
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0

paths:
  /board:
    get:
      security:
        - app2AppOauth:
          - board:read
      # ... other operation details
  /board/{row}/{column}:
    put:
      security:
        - user2AppOauth:
          - board:read
          - board:write
      # ... other operation details
```
```

--------------------------------

### Add Filter Parameters to Operations with x-supports-filters

Source: https://learn.openapis.org/overlay/example-add-filter-parameters.html

This snippet applies two inline query parameters ('month' and 'time_start') and a tag ('x-filters-added') to any operation where the 'x-supports-filters' extension is set to true. Use this to consistently add common parameter sets to specific operations.

```yaml
overlay: 1.0.0
info:
  title: Add filter parameters everywhere
  version: 1.0.0
actions:
- target: $.paths.*.*[?(@.x-supports-filters == true)]
  update:
    parameters:
      - name: month
        in: query
        description: Month number of event (1-12)
        required: false
        type: integer

      - name: time_start
        in: query
        description: Start time of event
        required: false
        type: string
    tags:
      - x-filters-added

```

--------------------------------

### Copy Schema Component using Overlay

Source: https://learn.openapis.org/overlay/example-copy-schema.html

This overlay configuration copies the 'Foo' schema component to a new 'Bar' schema component. Ensure the target schema ('Bar') is present before copying.

```yaml
overlay: 1.1.0
info:
  title: Copy a schema component
  version: 1.1.0
actions:
  - target: '$.components.schemas'
    description: Ensure the target schema is present
    update:
      Bar: {}
  - target: '$.components.schemas["Bar"]'
    copy: '$.components.schemas["Foo"]'
    description: Copy the Foo Schema to Bar

```

--------------------------------

### CommonMark Lists

Source: https://learn.openapis.org/specification/docs

Create unordered lists using hyphens or asterisks. Indentation creates nested lists.

```markdown
- Item 1
- Item 2
  - Item 2.1

```

--------------------------------

### Tic Tac Toe - Set Single Board Square

Source: https://learn.openapis.org/specification/parameters

Example of an operation to set a single square on a Tic Tac Toe board, including path parameters for row and column, and a JSON request body with an enum constraint.

```APIDOC
## PUT /board/{row}/{column}

### Description
Set a single board square in the Tic Tac Toe game.

### Method
PUT

### Endpoint
/board/{row}/{column}

### Parameters
#### Path Parameters
- **row** (integer) - Required - The row number of the square (1-3).
- **column** (integer) - Required - The column number of the square (1-3).

### Request Body
- **Required**: true
- **Content**: application/json
  - **Schema**: 
    - **type**: string
    - **enum**: [".", "X", "O"]

### Response
#### Success Response (200)
- **Example**: A successful response structure would be detailed here if provided in the source.
```

--------------------------------

### Reference a Component

Source: https://learn.openapis.org/specification/components

Use a Reference Object with the `$ref` field to point to a defined component. References can be absolute or relative URIs.

```yaml
$ref: 'https://gigantic-server.com/schemas/Monster/schema.yaml'
```

```yaml
$ref: './another_file.yaml#rowParam'
```

--------------------------------

### Server URL with Variables

Source: https://learn.openapis.org/specification/servers

Define server URLs with variable portions enclosed in curly braces. These variables must be further detailed in the 'variables' field.

```yaml
servers:
- url: https://{username}.server.com:{port}/{version}
```

--------------------------------

### OAuth 2.0 Configuration (Client Credentials & Authorization Code)

Source: https://learn.openapis.org/specification/security

Demonstrates the configuration of OAuth 2.0 security schemes using the OpenAPI specification. It covers the 'clientCredentials' and 'authorizationCode' grant types, including token and authorization URLs, and scopes.

```APIDOC
## OAuth 2.0 Configuration (Client Credentials & Authorization Code)

### Description
Demonstrates the configuration of OAuth 2.0 security schemes using the OpenAPI specification. It covers the 'clientCredentials' and 'authorizationCode' grant types, including token and authorization URLs, and scopes.

### Components Security Schemes
```yaml
components:
  securitySchemes:
    oauth2Profiles:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://learn.openapis.org/oauth/2.0/token
          scopes:
            board:read: Read the board
            board:write: Write to the board
        authorizationCode:
          authorizationUrl: https://learn.openapis.org/oauth/2.0/auth
          tokenUrl: https://learn.openapis.org/oauth/2.0/token
          scopes:
            board:read: Read the board
            board:write: Write to the board
```
```

--------------------------------

### Parameter Serialization Styles: Object Types (explode=true)

Source: https://learn.openapis.org/specification/parameters

Demonstrates object serialization styles ('simple', 'form', 'label', 'matrix') for an object named 'color' with 'explode=true'.

```yaml
style: | `simple` | `form` | `label` | `matrix`  
---
with `explode=true` | `R=1,G=2,B=3` | `R=1&G=2&B=3` | `.R=1.G=2.B=3` | `;R=1;G=2;B=3`
```

--------------------------------

### Define Schema and Parameter Components

Source: https://learn.openapis.org/specification/components

Define reusable schema and parameter components within the `components` object. These can be referenced elsewhere in the OpenAPI description.

```yaml
components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true

```

--------------------------------

### Set a single board square (with callback)

Source: https://learn.openapis.org/specification/callbacks

This operation allows placing a mark on a board. It accepts an optional `progressUrl` header for asynchronous responses, enabling the API provider to send status updates back to the consumer.

```APIDOC
## PUT /square

### Description
Places a mark on the board and retrieves the whole board and the winner (if any).

### Method
PUT

### Endpoint
/square

### Parameters
#### Header Parameters
- **progressUrl** (string) - Optional - Progress URL that should be called if asynchronous response is returned

### Request Body
- **mark** (object) - Required - Schema reference to the mark object

### Response
#### Success Response (200)
- **status** (object) - Description of the status object

#### Success Response (202)
- Description: Mark operation has not completed. Callback will be used to send notification once operation is complete
```

--------------------------------

### Parameter Serialization Styles: Primitive Types

Source: https://learn.openapis.org/specification/parameters

Illustrates the 'simple' and 'form' serialization styles for a primitive integer parameter named 'id'.

```yaml
style: | `simple` | `form` | `label` | `matrix`  
---
| `1234` | `id=1234` | `.1234` | `;id=1234`
```

--------------------------------

### CommonMark Links and Images

Source: https://learn.openapis.org/specification/docs

Create hyperlinks and embed images using standard markdown syntax. Specify the link text or alt text and the URL.

```markdown
[Link text](Link URL)
![Alt text](Image URL)

```

--------------------------------

### QUERY Method Support (OpenAPI 3.2+)

Source: https://learn.openapis.org/specification/http-methods

OpenAPI 3.2 introduces native support for the QUERY HTTP method, suitable for complex queries.

```APIDOC
## QUERY /products

### Description
Advanced product search.

### Method
QUERY

### Endpoint
/products

### Parameters
#### Request Body
- **filter** (object) - Required - The filter criteria for the search.
- **sort** (array) - Required - An array of strings specifying the sort order.
  - **items** (string) - Description for items in the sort array.

### Response
#### Success Response (200)
- **description** (string) - Search results
```

--------------------------------

### Apply API Key Security Globally and Per Operation

Source: https://learn.openapis.org/specification/security

Apply a defined API Key security scheme globally using the top-level `security` property and per-operation using the operation's `security` property. An empty array is used when no parameters are needed for the scheme.

```yaml
openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
security:
  - defaultApiKey: []
paths:
  /board:
    get:
      security:
        - defaultApiKey: []
```

--------------------------------

### Update Primitive Values in Overlay

Source: https://learn.openapis.org/upgrading/overlay-v1.0-to-v1.1

Demonstrates updating primitive values like strings directly, which is now fully supported in Overlay 1.1, unlike previous versions that required updating the parent object.

```yaml
overlay: 1.1.0
info:
  title: Targeted Overlay
  version: 1.0.0
actions:
  - target: $.paths['/foo'].get.description
    update: This is the new description
  - target: $.paths['/bar'].get.description
    update: This is the updated description

```

--------------------------------

### Add MIT License Overlay

Source: https://learn.openapis.org/overlay/example-add-license.html

Use this Overlay to add or update the license information in an OpenAPI description. It sets the license name to MIT and provides a URL to the MIT license details.

```yaml
overlay: 1.0.0
info:
  title: Add MIT license
  version: 1.0.0
actions:
  - target: '$.info'
    update:
      license:
        name: MIT
        url: https://opensource.org/licenses/MIT        

```

--------------------------------

### Operation with Progress URL Header

Source: https://learn.openapis.org/specification/callbacks

Defines an operation that accepts an optional 'progressUrl' header for asynchronous callbacks. A 202 response indicates the operation is not yet complete.

```yaml
put:
  summary: Set a single board square
  description: Places a mark on the board and retrieves the whole board and the winner (if any).
  tags:
    - Gameplay
  operationId: put-square
  parameters:
    - name: progressUrl
      in: header
      description: Progress URL that should be called if asynchronous response is returned
      required: false
      schema:
        type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/mark"
  responses:
    "200":
      description: "OK"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/status"
    "202":
      description: Mark operation has not completed. Callback will be used to send notification once operation is complete

```

--------------------------------

### Server Variables Definition

Source: https://learn.openapis.org/specification/servers

Detail server URL variables, including their default values, allowed enumerated values, and descriptions. The 'default' value is mandatory for server variables.

```yaml
servers:
- url: https://{username}.server.com:{port}/{version}
  variables:
    username:
      default: demo
      description: This value is assigned by the service provider.
    port:
      enum:
        - "8443"
        - "443"
      default: "8443"
    version:
      default: v1
```

--------------------------------

### Operation Object Details

Source: https://learn.openapis.org/specification/paths

Shows an Operation Object, detailing its summary, description, parameters, and responses. Parameters and payload are described on other pages.

```yaml
paths:
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      parameters:
        ...
      responses:
        ...

```

--------------------------------

### Update Binary File Upload Descriptions

Source: https://learn.openapis.org/upgrading/v3.0-to-v3.1

In OpenAPI 3.1, use `contentEncoding` and `contentMediaType` for file uploads. For binary files, the schema type remains `string` but the `format` is removed.

```yaml
# OpenAPI 3.0
requestBody:
  content:
    application/octet-stream:
      schema:
        type: string
        format: binary
```

```yaml
# OpenAPI 3.1
requestBody:
  content:
    application/octet-stream: {}
```

--------------------------------

### Additional Operations for Custom Methods in OpenAPI 3.2+

Source: https://learn.openapis.org/specification/http-methods

Shows how to use `additionalOperations` to define custom HTTP methods not covered by standard OpenAPI operations, such as LINK.

```yaml
# OpenAPI 3.2
paths:
  /documents/{id}:
    additionalOperations:
      LINK:
        summary: Link related documents
        parameters:
          - name: id
            in: path
            required: true
            schema: { type: string }
        requestBody:
          required: true
          content:
            application/json:
              schema:
                type: object
                properties:
                  targetDocument:
                    type: string
                  relationship:
                    type: string
        responses:
          '204':
            description: Link created successfully
```

--------------------------------

### Standard HTTP Methods

Source: https://learn.openapis.org/specification/http-methods

OpenAPI has always supported standard HTTP methods as operation keys in path items for defining API operations.

```APIDOC
## GET /users

### Description
Retrieve users.

### Method
GET

### Endpoint
/users

### Response
#### Success Response (200)
- **description** (string) - User list

## POST /users

### Description
Create a new user.

### Method
POST

### Endpoint
/users

### Response
#### Success Response (201)
- **description** (string) - User created

## PUT /users

### Description
Replace all users.

### Method
PUT

### Endpoint
/users

## DELETE /users

### Description
Delete all users.

### Method
DELETE

### Endpoint
/users

## OPTIONS /users

### Description
Get allowed methods for users endpoint.

### Method
OPTIONS

### Endpoint
/users

## HEAD /users

### Description
Get user list headers.

### Method
HEAD

### Endpoint
/users

## PATCH /users

### Description
Update users.

### Method
PATCH

### Endpoint
/users

## TRACE /users

### Description
Trace users endpoint.

### Method
TRACE

### Endpoint
/users
```

--------------------------------

### Correct JSONPath for Property Access

Source: https://learn.openapis.org/upgrading/overlay-v1.0-to-v1.1

Illustrates the correct JSONPath syntax for accessing properties, particularly those with hyphens or special characters, by using square brackets.

```jsonpath
$.paths.*.get[?(@.x-oai-traits[?(@ == 'paged')])]
```

```jsonpath
$.paths.*.get[?(@['x-oai-traits'][?(@ == 'paged')])]
```

--------------------------------

### OAuth 2.0 Segregation by Grant Type and Scopes

Source: https://learn.openapis.org/specification/security

Illustrates how to define separate OAuth 2.0 security schemes to differentiate between grant types (e.g., client credentials vs. authorization code) and available scopes for specific operations.

```APIDOC
## OAuth 2.0 Segregation by Grant Type and Scopes

### Description
Illustrates how to define separate OAuth 2.0 security schemes to differentiate between grant types (e.g., client credentials vs. authorization code) and available scopes for specific operations.

### Components Security Schemes
```yaml
components:
  securitySchemes:
    app2AppOauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://learn.openapis.org/oauth/2.0/token
          scopes:
            # Only reading the board allow with delegated access
            board:read: Read the board
    user2AppOauth:
        type: oauth2
        flows:
          authorizationCode:
            authorizationUrl: https://learn.openapis.org/oauth/2.0/auth
            tokenUrl: https://learn.openapis.org/oauth/2.0/token
            scopes:
              # Reads and writes permitted via authorization code flow
              board:read: Read the board
              board:write: Write to the board
```
```

--------------------------------

### CommonMark Headings

Source: https://learn.openapis.org/specification/docs

Use markdown syntax for headings to structure documentation. Supports levels 1 through 3.

```markdown
# Level 1
## Level 2
### Level 3

```

--------------------------------

### Response Object with Description and Content

Source: https://learn.openapis.org/specification/paths

Details the Response Object, which includes a mandatory description and the 'content' field describing the response payload. The 'content' format is explained on a separate page.

```yaml
paths:
  /board:
    get:
      responses:
        "200":
          description: Everything went fine.
          content:
            ...

```

--------------------------------

### Path Parameters for Tic Tac Toe

Source: https://learn.openapis.org/specification/parameters

Defines path parameters 'row' and 'column' for an operation. Both are required integers between 1 and 3.

```yaml
paths:
  # Single square operations
  /board/{row}/{column}:
    parameters:
      - name: row
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 3
      - name: column
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 3
```

--------------------------------

### Parameter Serialization Styles: Object Types (explode=false)

Source: https://learn.openapis.org/specification/parameters

Illustrates object serialization styles ('simple', 'form', 'label', 'matrix') for an object named 'color' with 'explode=false'.

```yaml
style: | `simple` | `form` | `label` | `matrix`  
---
with `explode=false` | `R,1,G,2,B,3` | `color=R,1,G,2,B,3` | `.R.1.G.2.B.3` | `;color=R,1,G,2,B,3`
```

--------------------------------

### Enhanced Server Fields with Names (OpenAPI 3.2+)

Source: https://learn.openapis.org/specification/servers

Use the 'name' field for easier identification and reference of servers, particularly useful for tool integration and documentation clarity.

```yaml
servers:
- name: Production
  url: https://api.example.com/v1
  description: Production server for live traffic
- name: Staging
  url: https://staging-api.example.com/v1
  description: Staging environment for testing
- name: Development
  url: http://localhost:3000/v1
  description: Local development server
```
Tokens:
Raw