### Parameter Examples in OpenAPI

Source: https://swagger.io/specification

Reference examples for parameters using the '$ref' keyword. This allows for centralized definition of example values.

```yaml
parameters:
  - name: zipCode
    in: query
    schema:
      type: string
      format: zip-code
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'
```

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

### Multiple Server Object Examples

Source: https://swagger.io/specification

Examples of defining multiple servers in JSON and YAML formats.

```json
  1. {
  2.   "servers": [
  3.     {
  4.       "url": "https://development.gigantic-server.com/v1",
  5.       "description": "Development server"
  6.     },
  7.     {
  8.       "url": "https://staging.gigantic-server.com/v1",
  9.       "description": "Staging server"
  10.     },
  11.     {
  12.       "url": "https://api.gigantic-server.com/v1",
  13.       "description": "Production server"
  14.     }
  15.   ]
  16. }
```

```yaml
  1. servers:
  2.   - url: https://development.gigantic-server.com/v1
  3.     description: Development server
  4.   - url: https://staging.gigantic-server.com/v1
  5.     description: Staging server
  6.   - url: https://api.gigantic-server.com/v1
  7.     description: Production server
```

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

### Paths Object Example (YAML)

Source: https://swagger.io/specification

An example of the Paths Object in YAML format, defining a '/pets' path with a GET operation.

```yaml
/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'
```

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

### Single Server Object Examples

Source: https://swagger.io/specification

Examples of a single server object in JSON and YAML formats.

```json
  1. {
  2.   "url": "https://development.gigantic-server.com/v1",
  3.   "description": "Development server"
  4. }
```

```yaml
  1. url: https://development.gigantic-server.com/v1
  2. description: Development server
```

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

### Response Object with Headers and Example

Source: https://swagger.io/specification

Example of a Response Object for a plain text response, including an example and rate limit headers.

```json
{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      },
      "example": "whoa!"
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}
```

```yaml
description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer
```

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

### Server Variable Configuration Examples

Source: https://swagger.io/specification

Examples of server URL template substitution using variables in JSON and YAML formats.

```json
  1. {
  2.   "servers": [
  3.     {
  4.       "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
  5.       "description": "The production API server",
  6.       "variables": {
  7.         "username": {
  8.           "default": "demo",
  9.           "description": "A user-specific subdomain. Use `demo` for a free sandbox environment."
  10.         },
  11.         "port": {
  12.           "enum": ["8443", "443"],
  13.           "default": "8443"
  14.         },
  15.         "basePath": {
  16.           "default": "v2"
  17.         }
  18.       }
  19.     }
  20.   ]
  21. }
```

```yaml
  1. servers:
  2.   - url: https://{username}.gigantic-server.com:{port}/{basePath}
  3.     description: The production API server
  4.     variables:
  5.       username:
  6.         # note! no enum here means it is an open value
  7.         default: demo
  8.         description: A user-specific subdomain. Use `demo` for a free sandbox environment.
  9.       port:
  10.         enum:
  11.           - '8443'
  12.           - '443'
  13.         default: '8443'
  14.       basePath:
  15.         # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
  16.         default: v2
```

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

### Paths Object Example (JSON)

Source: https://swagger.io/specification

An example of the Paths Object in JSON format, defining a '/pets' path with a GET operation.

```json
{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

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

### License Object Examples

Source: https://swagger.io/specification

Examples of a license object in JSON and YAML formats.

```json
  1. {
  2.   "name": "Apache 2.0",
  3.   "identifier": "Apache-2.0"
  4. }
```

```yaml
  1. name: Apache 2.0
  2. identifier: Apache-2.0
```

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

### Path Parameter Example (String)

Source: https://swagger.io/specification

Example of a path parameter named 'username' which expects a string value.

```APIDOC
## Path Parameter: username

### Description
Username to fetch.

### In
path

### Name
username

### Required
true

### Schema
- type: string
```

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

### Components Object Example (YAML)

Source: https://swagger.io/specification

This example shows the equivalent structure of the Components Object using YAML syntax, which is often preferred for its readability.

```yaml
  1. components:
  2.   schemas:
  3.     GeneralError:
  4.       type: object
  5.       properties:
  6.         code:
  7.           type: integer
  8.           format: int32
  9.         message:
  10.           type: string
  11.     Category:
  12.       type: object
  13.       properties:
  14.         id:
  15.           type: integer
  16.           format: int64
  17.         name:
  18.           type: string
  19.     Tag:
  20.       type: object
  21.       properties:
  22.         id:
  23.           type: integer
  24.           format: int64
  25.         name:
  26.           type: string
  27.   parameters:
  28.     skipParam:
  29.       name: skip
  30.       in: query
  31.       description: number of items to skip
  32.       required: true
  33.       schema:
  34.         type: integer
  35.         format: int32
  36.     limitParam:
  37.       name: limit
  38.       in: query
  39.       description: max records to return
  40.       required: true
  41.       schema:
  42.         type: integer
  43.         format: int32
  44.   responses:
  45.     NotFound:
  46.       description: Entity not found.
  47.     IllegalInput:
  48.       description: Illegal input for operation.
  49.     GeneralError:
  50.       description: General Error
  51.       content:
  52.         application/json:
  53.           schema:
  54.             $ref: '#/components/schemas/GeneralError'
  55.   securitySchemes:
  56.     api_key:
  57.       type: apiKey
  58.       name: api-key
  59.       in: header
  60.     petstore_auth:
  61.       type: oauth2
  62.       flows:
  63.         implicit:
  64.           authorizationUrl: https://example.org/api/oauth/dialog
  65.           scopes:
  66.             write:pets: modify pets in your account
  67.             read:pets: read your pets

```

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

### Header Parameter Example (Array of int64)

Source: https://swagger.io/specification

Example of a header parameter named 'token' which expects an array of 64-bit integers.

```APIDOC
## Header Parameter: token

### Description
Token to be passed as a header.

### In
header

### Name
token

### Required
true

### Schema
- type: array
- items:
  - type: integer
  - format: int64

### Style
simple
```

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

### operationRef Examples

Source: https://swagger.io/specification

Examples demonstrating how to reference operations using relative and URI operationRefs.

```APIDOC
## operationRef Examples

As references to `operationId` MAY NOT be possible (the `operationId` is an optional field in an Operation Object), references MAY also be made through a relative `operationRef`:

```yaml
1. links:
2.   UserRepositories:
3.     # returns array of '#/components/schemas/repository'
4.     operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
5.     parameters:
6.       username: $response.body#/username
```

or a URI `operationRef`:

```yaml
1. links:
2.   UserRepositories:
3.     # returns array of '#/components/schemas/repository'
4.     operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
5.     parameters:
6.       username: $response.body#/username
```

Note that in the use of `operationRef` the _escaped forward-slash_ is necessary when using JSON Pointer, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively, when using JSON Pointer as URI fragments.
```

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

### Callback Object Examples

Source: https://swagger.io/specification

Examples demonstrating how to define callback URLs using runtime expressions, including dynamic query parameters and hard-coded server URLs.

```APIDOC
### Callback Object Examples

The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is similar to a webhook, but differs in that the callback only occurs because of the initial request that sent the `queryUrl`.
```yaml
myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed
```

The following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body.
```yaml
transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed
```
```

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

### Response Examples in OpenAPI

Source: https://swagger.io/specification

Reference examples for successful responses using the '$ref' keyword. This is useful for providing pre-defined success scenarios.

```yaml
responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'
```

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

### Contact Object Examples

Source: https://swagger.io/specification

Examples of a contact object in JSON and YAML formats.

```json
  1. {
  2.   "name": "API Support",
  3.   "url": "https://www.example.com/support",
  4.   "email": "support@example.com"
  5. }
```

```yaml
  1. name: API Support
  2. url: https://www.example.com/support
  3. email: support@example.com
```

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

### Request Body Examples in OpenAPI

Source: https://swagger.io/specification

Define inline examples for JSON and XML content types within a request body. External values can be referenced for text-based examples.

```yaml
requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value:
            foo: bar
        bar:
          summary: A bar example
          value:
            bar: baz
    application/xml:
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: https://example.org/examples/address-example.xml
    text/plain:
      examples:
        textExample:
          summary: This is a text example
          externalValue: https://foo.bar/examples/address-example.txt
```

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

### Components Object Example (JSON)

Source: https://swagger.io/specification

This example demonstrates the structure of the Components Object in JSON format, including schemas, parameters, responses, and security schemes.

```json
  1. "components": {
  2.   "schemas": {
  3.     "GeneralError": {
  4.       "type": "object",
  5.       "properties": {
  6.         "code": {
  7.           "type": "integer",
  8.           "format": "int32"
  9.         },
  10.         "message": {
  11.           "type": "string"
  12.         }
  13.       }
  14.     },
  15.     "Category": {
  16.       "type": "object",
  17.       "properties": {
  18.         "id": {
  19.           "type": "integer",
  20.           "format": "int64"
  21.         },
  22.         "name": {
  23.           "type": "string"
  24.         }
  25.       }
  26.     },
  27.     "Tag": {
  28.       "type": "object",
  29.       "properties": {
  30.         "id": {
  31.           "type": "integer",
  32.           "format": "int64"
  33.         },
  34.         "name": {
  35.           "type": "string"
  36.         }
  37.       }
  38.     }
  39.   },
  40.   "parameters": {
  41.     "skipParam": {
  42.       "name": "skip",
  43.       "in": "query",
  44.       "description": "number of items to skip",
  45.       "required": true,
  46.       "schema": {
  47.         "type": "integer",
  48.         "format": "int32"
  49.       }
  50.     },
  51.     "limitParam": {
  52.       "name": "limit",
  53.       "in": "query",
  54.       "description": "max records to return",
  55.       "required": true,
  56.       "schema" : {
  57.         "type": "integer",
  58.         "format": "int32"
  59.       }
  60.     }
  61.   },
  62.   "responses": {
  63.     "NotFound": {
  64.       "description": "Entity not found."
  65.     },
  66.     "IllegalInput": {
  67.       "description": "Illegal input for operation."
  68.     },
  69.     "GeneralError": {
  70.       "description": "General Error",
  71.       "content": {
  72.         "application/json": {
  73.           "schema": {
  74.             "$ref": "#/components/schemas/GeneralError"
  75.           }
  76.         }
  77.       }
  78.     }
  79.   },
  80.   "securitySchemes": {
  81.     "api_key": {
  82.       "type": "apiKey",
  83.       "name": "api-key",
  84.       "in": "header"
  85.     },
  86.     "petstore_auth": {
  87.       "type": "oauth2",
  88.       "flows": {
  89.         "implicit": {
  90.           "authorizationUrl": "https://example.org/api/oauth/dialog",
  91.           "scopes": {
  92.             "write:pets": "modify pets in your account",
  93.             "read:pets": "read your pets"
  94.           }
  95.         }
  96.       }
  97.     }
  98.   }
  99. }

```

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

### XML Serialization Examples

Source: https://swagger.io/specification

Examples demonstrating how the XML object modifies the output structure for various schema types.

```APIDOC
## XML Serialization Examples

### XML Name Replacement
```json
{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}
```

### XML Attribute, Prefix and Namespace
```json
{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "xml": { "attribute": true }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "https://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}
```
```

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

### Example Object Structure

Source: https://swagger.io/specification

Defines the fields available for an Example Object in the OpenAPI specification.

```APIDOC
## Example Object

### Description
The Example Object provides a way to define examples for parameters or media types. It supports both embedded values and external references.

### Fields
- **summary** (string) - Short description for the example.
- **description** (string) - Long description for the example. CommonMark syntax may be used.
- **value** (Any) - Embedded literal example. Mutually exclusive with externalValue.
- **externalValue** (string) - A URI that identifies the literal example. Mutually exclusive with value.
```

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

### Path Item Object Example

Source: https://swagger.io/specification

Examples of a Path Item Object defined in both JSON and YAML formats.

```json
{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}
```

```yaml
get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*':
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        text/html:
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
  - name: id
    in: path
    description: ID of pet to use
    required: true
    schema:
      type: array
      items:
        type: string
    style: simple
```

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

### Object Schema with Examples

Source: https://swagger.io/specification

Defines an object schema with properties and includes an 'examples' array to provide sample data. Useful for illustrating expected data formats.

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"],
  "examples": [
    {
      "name": "Puma",
      "id": 1
    }
  ]
}
```

```yaml
type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1
```

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

### JSON Media Type with Examples

Source: https://swagger.io/specification

Defines the 'application/json' media type with schema reference and multiple examples for different pet types.

```json
1. {
2.   "application/json": {
3.     "schema": {
4.       "$ref": "#/components/schemas/Pet"
5.     },
6.     "examples": {
7.       "cat": {
8.         "summary": "An example of a cat",
9.         "value": {
10.           "name": "Fluffy",
11.           "petType": "Cat",
12.           "color": "White",
13.           "gender": "male",
14.           "breed": "Persian"
15.         }
16.       },
17.       "dog": {
18.         "summary": "An example of a dog with a cat's name",
19.         "value": {
20.           "name": "Puma",
21.           "petType": "Dog",
22.           "color": "Black",
23.           "gender": "Female",
24.           "breed": "Mixed"
25.         }
26.       },
27.       "frog": {
28.         "$ref": "#/components/examples/frog-example"
29.       }
30.     }
31.   }
32. }
```

```yaml
1. application/json:
2.   schema:
3.     $ref: '#/components/schemas/Pet'
4.   examples:
5.     cat:
6.       summary: An example of a cat
7.       value:
8.         name: Fluffy
9.         petType: Cat
10.         color: White
11.         gender: male
12.         breed: Persian
13.     dog:
14.       summary: An example of a dog with a cat's name
15.       value:
16.         name: Puma
17.         petType: Dog
18.         color: Black
19.         gender: Female
20.         breed: Mixed
21.     frog:
22.       $ref: '#/components/examples/frog-example'
```

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

### Reference Object Example (JSON)

Source: https://swagger.io/specification

Demonstrates a basic Reference Object using JSON format to point to a schema component.

```json
{
  "$ref": "#/components/schemas/Pet"
}
```

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

### Info Object Example (YAML)

Source: https://swagger.io/specification

This YAML representation shows the same Info Object fields as the JSON example, illustrating an alternative format for OpenAPI descriptions.

```yaml
title: Example Pet Store App
summary: A pet store manager.
description: This is an example server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
```

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

### Binary File Upload Example (PNG)

Source: https://swagger.io/specification

Defines content for a PNG image as a binary file, omitting the schema.

```yaml
1. # a PNG image as a binary file:
2. content:
3.   image/png: {}
```

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

### HTTP Request Example for Callback Context

Source: https://swagger.io/specification

This is an example HTTP request that provides context for evaluating runtime expressions used in callbacks. It includes headers, a body, and query parameters.

```http
POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 188

{
  "failedUrl": "https://clientdomain.com/failed",
  "successUrls": [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ]
}
```

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

### Define Request Body with Referenced Schema and Examples (JSON)

Source: https://swagger.io/specification

Illustrates defining a request body with a schema reference and multiple examples for different media types, including JSON, XML, text, and a wildcard.

```json
{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User Example",
          "externalValue": "https://foo.bar/examples/user-example.json"
        }
      }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User example in XML",
          "externalValue": "https://foo.bar/examples/user-example.xml"
        }
      }
    },
    "text/plain": {
      "examples": {
        "user": {
          "summary": "User example in Plain text",
          "externalValue": "https://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user": {
          "summary": "User example in other format",
          "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}
```

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

### Example Object

Source: https://swagger.io/specification

An object grouping an internal or external example value with metadata like summary and description, used for demonstrating property, parameter, and object usage.

```APIDOC
## Example Object
An object grouping an internal or external example value with basic `summary` and `description` metadata. This object is typically used in fields named `examples` (plural), and is a referenceable alternative to older `example` (singular) fields that do not support referencing or metadata. 
Examples allow demonstration of the usage of properties, parameters and objects within OpenAPI.
```

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

### Reference Object Example (YAML)

Source: https://swagger.io/specification

Illustrates a Reference Object using YAML format for referencing a schema component.

```yaml
$ref: '#/components/schemas/Pet'
```

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

### Responses Object Example

Source: https://swagger.io/specification

Example of a Responses Object showing a 200 success response and a default error response.

```APIDOC
## Responses Object Example

### Description
A 200 response for a successful operation and a default response for others (implying an error).

### Request Example
```json
{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}
```
```

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

### Payload Example for allOf with Discriminator

Source: https://swagger.io/specification

A payload example that matches the 'Cat' schema when validated against the 'Pet' schema, due to the 'petType' property and the 'allOf' composition.

```json
{
  "petType": "Cat",
  "name": "Misty"
}
```

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

### Callback Object Example using Query Parameter

Source: https://swagger.io/specification

This example demonstrates a Callback Object where the callback URL is dynamically determined by a query string parameter from the initial request. This is useful when the client provides a URL for the API provider to send notifications to.

```yaml
myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed
```

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

### Arbitrary Binary File Upload Example

Source: https://swagger.io/specification

Defines content for an arbitrary binary file using 'application/octet-stream'.

```yaml
1. # an arbitrary binary file:
2. content:
3.   application/octet-stream: {}
```

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

### HTTP Response Example for Callback Context

Source: https://swagger.io/specification

This is an example HTTP response that provides context for evaluating runtime expressions used in callbacks. It includes status code and headers.

```http
201 Created
Location: https://example.org/subscription/1
```

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

### Define Request Body with Referenced Schema and Examples (YAML)

Source: https://swagger.io/specification

Shows the YAML equivalent for defining a request body with a schema reference and multiple examples across various media types.

```yaml
description: user to add to the system
content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example
        externalValue: https://foo.bar/examples/user-example.json
  application/xml:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: https://foo.bar/examples/user-example.xml
  text/plain:
    examples:
      user:
        summary: User example in plain text
        externalValue: https://foo.bar/examples/user-example.txt
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: https://foo.bar/examples/user-example.whatever
```

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

### Response Object Examples

Source: https://swagger.io/specification

Examples of Response Objects for different scenarios: array of complex types, string type, plain text with headers, and no return value.

```APIDOC
## Response Object Examples

### Response of an array of a complex type
```json
{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}
```

### Response with a string type
```json
{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }
}
```

### Plain text response with headers
```json
{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      },
      "example": "whoa!"
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}
```

### Response with no return value
```json
{
  "description": "object created"
}
```
```

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

### Callback Object Example with Hardcoded Server and Dynamic Query Parameters

Source: https://swagger.io/specification

This example shows a Callback Object with a hardcoded server URL, but the query string parameters are populated dynamically from properties within the request body. This is useful for sending specific data from the request to a notification server.

```yaml
transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed
```

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

### Query Parameter Example (Array of String, Form Style)

Source: https://swagger.io/specification

Example of an optional query parameter named 'id' which expects an array of strings and allows multiple values by repeating the parameter.

```APIDOC
## Query Parameter: id

### Description
ID of the object to fetch.

### In
query

### Name
id

### Required
false

### Schema
- type: array
- items:
  - type: string

### Style
form

### Explode
true
```

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

### Basic Authentication Security Scheme

Source: https://swagger.io/specification

Example configuration for HTTP Basic authentication.

```json

  1. {
  2.   "type": "http",
  3.   "scheme": "basic"
  4. }
```

```yaml

  1. type: http
  2. scheme: basic
```

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

### External Documentation Object Example

Source: https://swagger.io/specification

Provides a reference to external documentation using a description and a URL.

```json
  1. {
  2.   "description": "Find more info here",
  3.   "url": "https://example.com"
  4. }
```

```yaml
  1. description: Find more info here
  2. url: https://example.com
```

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

### Payload Example for Discriminator Mapping

Source: https://swagger.io/specification

A payload example that maps to the 'Dog' schema using the explicit mapping defined in the discriminator, where 'dog' value maps to the 'Dog' schema.

```json
{
  "petType": "dog",
  "bark": "soft"
}
```

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

### Define a Simple Integer Header

Source: https://swagger.io/specification

Example of a simple integer header definition using schema.

```JSON
  1. "X-Rate-Limit-Limit": {
  2.   "description": "The number of allowed requests in the current period",
  3.   "schema": {
  4.     "type": "integer"
  5.   }
  6. }
```

```YAML
  1. X-Rate-Limit-Limit:
  2.   description: The number of allowed requests in the current period
  3.   schema:
  4.     type: integer
```

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

### API Key Security Scheme

Source: https://swagger.io/specification

Example configuration for an API key passed in the header.

```json

  1. {
  2.   "type": "apiKey",
  3.   "name": "api-key",
  4.   "in": "header"
  5. }
```

```yaml

  1. type: apiKey
  2. name: api-key
  3. in: header
```

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

### Response Object for Simple String Type

Source: https://swagger.io/specification

Example of a Response Object describing a simple string response.

```json
{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }
}
```

```yaml
description: A simple string response
content:
  text/plain:
    schema:
      type: string
```

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

### Implicit OAuth2 Security Scheme

Source: https://swagger.io/specification

Example configuration for the OAuth2 implicit flow.

```json

  1. {
  2.   "type": "oauth2",
  3.   "flows": {
  4.     "implicit": {
  5.       "authorizationUrl": "https://example.com/api/oauth/dialog",
  6.       "scopes": {
  7.         "write:pets": "modify pets in your account",
  8.         "read:pets": "read your pets"
  9.       }
  10.     }
  11.   }
  12. }
```

```yaml

  1. type: oauth2
  2. flows:
  3.   implicit:
  4.     authorizationUrl: https://example.com/api/oauth/dialog
  5.     scopes:
  6.       write:pets: modify pets in your account
  7.       read:pets: read your pets
```

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

### Example: Linking from Response Body

Source: https://swagger.io/specification

Illustrates how to define a link that uses a value from the response body to call another operation.

```APIDOC
## GET /users/{id}

### Description
Retrieves a user by their ID.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (`string`) - Required - The user identifier.

### Responses
#### Success Response (200)
- **uuid** (`string`) - The unique user ID in UUID format.

### Links
#### address
- **operationId**: getUserAddressByUUID
- **parameters**:
  - **userUuid** (`string`) - The user's UUID, taken from the response body's `uuid` field (`$response.body#/uuid`).

---

## GET /users/address/by-uuid

### Description
Retrieves the address for a given user UUID.

### Method
GET

### Endpoint
/users/address/by-uuid

### Parameters
#### Query Parameters
- **userUuid** (`string`) - Required - The user's UUID.

### Responses
#### Success Response (200)
- **address** (`string`) - The user's address.
```

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

### Define Media Types

Source: https://swagger.io/specification

Examples of valid media type strings that can be used within an OpenAPI definition.

```text
  1.   text/plain; charset=utf-8
  2.   application/json
  3.   application/vnd.github+json
  4.   application/vnd.github.v3+json
  5.   application/vnd.github.v3.raw+json
  6.   application/vnd.github.v3.text+json
  7.   application/vnd.github.v3.html+json
  8.   application/vnd.github.v3.full+json
  9.   application/vnd.github.v3.diff
  10.   application/vnd.github.v3.patch
```

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

### Arbitrary JSON Content Example

Source: https://swagger.io/specification

Defines content for arbitrary JSON without specific schema constraints.

```yaml
1. # arbitrary JSON without constraints beyond being syntactically valid:
2. content:
3.   application/json: {}
```

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

### Define a Header with Content

Source: https://swagger.io/specification

Example of a header requiring a specific pattern using the content field to avoid percent-encoding issues.

```JSON
  1. "ETag": {
  2.   "required": true,
  3.   "content": {
  4.     "text/plain": {
  5.       "schema": {
  6.         "type": "string",
  7.         "pattern": "^\""
  8.       }
  9.     }
  10.   }
  11. }
```

```YAML
  1. ETag:
  2.   required: true
  3.   content:
  4.     text/plain:
  5.       schema:
  6.         type: string
  7.         pattern: ^"
```

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

### Define 200 and Default Responses

Source: https://swagger.io/specification

Example of a Responses Object defining a successful 200 response and a default response for errors.

```json
{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}
```

```yaml
'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'
```

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

### Info Object Example (JSON)

Source: https://swagger.io/specification

This JSON object demonstrates the structure and fields of the Info Object, including title, summary, description, termsOfService, contact, license, and version.

```json
{
  "title": "Example Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is an example server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}
```

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

### Payload Example for Discriminator

Source: https://swagger.io/specification

A payload example where the 'petType' property indicates that the 'Cat' schema should be used for deserialization.

```json
{
  "id": 12345,
  "petType": "Cat"
}
```

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

### Example: Linking from Request Path Parameter

Source: https://swagger.io/specification

Demonstrates how to define a link that uses a request path parameter to call another operation.

```APIDOC
## GET /users/{id}

### Description
Retrieves a user by their ID.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (`string`) - Required - The user identifier.

### Responses
#### Success Response (200)
- **uuid** (`string`) - The unique user ID in UUID format.

### Links
#### address
- **operationId**: getUserAddress
- **parameters**:
  - **userid** (`string`) - The user identifier, taken from the request path parameter `id` (`$request.path.id`).

---

## GET /users/{userid}/address

### Description
Retrieves the address for a given user ID.

### Method
GET

### Endpoint
/users/{userid}/address

### Parameters
#### Path Parameters
- **userid** (`string`) - Required - The user identifier.

### Responses
#### Success Response (200)
- **address** (`string`) - The user's address.
```

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

### Example Data for Form Query String

Source: https://swagger.io/specification

Sample data demonstrating the use of 'formulas' as an exploded object and 'words' as a non-exploded array in a form query string.

```yaml
1. formulas:
2.   a: x+y
3.   b: x/y
4.   c: x^y
5. words:
6. - math
7. - is
8. - fun
```

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

### Path Templating Matching Examples

Source: https://swagger.io/specification

Illustrates path templating matching rules. Concrete paths are matched before templated ones. Identical templated paths with different names are invalid. Ambiguous resolutions may occur.

```text
1.   /pets/{petId}
2.   /pets/mine
```

```text
1.   /pets/{petId}
2.   /pets/{name}
```

```text
1.   /{entity}/me
2.   /books/{id}
```

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

### Query Parameter Example (Free Form Object)

Source: https://swagger.io/specification

Example of a free-form query parameter named 'freeForm' that allows undefined parameters of a specific type (integer).

```APIDOC
## Query Parameter: freeForm

### Description
Allows undefined parameters of a specific type.

### In
query

### Name
freeForm

### Schema
- type: object
- additionalProperties:
  - type: integer

### Style
form
```