### Path Item Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates the Path Item Object in YAML format, detailing operations like GET, parameters, and responses for a specific path.

```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
```

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

### Path Item Object Example - GET /pets

Source: https://spec.openapis.org/oas/v3.1.0.html

This example demonstrates a Path Item Object for the '/pets' path, defining a GET operation that returns all pets accessible to the user.

```APIDOC
## GET /pets

### Description
Returns all pets from the system that the user has access to.

### Method
GET

### Endpoint
/pets

### Responses
#### Success Response (200)
- **description**: A list of pets.
  **content**: application/json
    **schema**: array of items referencing '#/components/schemas/pet'
```

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

### Media Type Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Examples for JSON media types, referencing schemas and other examples.

```APIDOC
## Media Type Examples

This section demonstrates how to define examples for media types, particularly `application/json`.

### Example: JSON Pet Examples

```yaml
application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"
```
```

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

### Path Item Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates the Path Item Object in JSON format, detailing operations like GET, parameters, and responses for a specific path.

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

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

### Example Object in Parameter

Source: https://spec.openapis.org/oas/v3.1.0.html

Shows how to reference an example for a query parameter using `$ref`.

```APIDOC
## Example Object in Parameter

### Parameters
- **name**: `zipCode`
  - **in**: `query`
  - **schema**: `string` (format: `zip-code`)
  - **examples**:
    - **zip-example** - `$ref: '#/components/examples/zip-example'`
```

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

### Path Item Object Example - GET /pets/{id}

Source: https://spec.openapis.org/oas/v3.1.0.html

This example shows a Path Item Object for a path with a parameter, defining a GET operation to find pets by ID and including a path parameter definition.

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

### Description
Returns pets based on ID.

### Method
GET

### Endpoint
/pets/{id}

### Parameters
#### Path Parameters
- **id** (array of string) - Required - ID of pet to use

### Responses
#### Success Response (200)
- **description**: pet response
  **content**: */*
    **schema**: array of items referencing '#/components/schemas/Pet'
#### Error Response (default)
- **description**: error payload
  **content**: text/html
    **schema**: referencing '#/components/schemas/ErrorModel'
```

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

### Example: Using operationRef

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates how to use `operationRef` for linking, including examples with relative and absolute URIs.

```APIDOC
## Example: Using operationRef

### Description
Illustrates how to use `operationRef` for linking, including examples with relative and absolute URIs.

### Request Example (Conceptual)
```yaml
links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username
```

### Absolute operationRef Example (Conceptual)
```yaml
links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username
```

Note: In `operationRef`, the escaped forward-slash (`~1`) is necessary when using JSON references.
```

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

### Example Object in Response

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates how to reference an example for a successful response using `$ref`.

```APIDOC
## Example Object in Response

### 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'`
```

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

### JSON Media Type Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Define examples for JSON content using schema references and direct values. Supports referencing external examples.

```yaml
{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}
```

```yaml
application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"
```

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

### Define a model with an example value

Source: https://spec.openapis.org/oas/v3.1.0.html

Include an 'example' field to provide a sample JSON object that conforms to the schema.

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

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

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

### Multiple Server Objects Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Demonstrates how to define multiple servers for different environments.

```APIDOC
## Multiple Servers Example

The following shows how multiple servers can be described, for example, at the OpenAPI Object’s `servers`:

```json
{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}
```

```yaml
servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server
```
```

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

### Example Object in Request Body

Source: https://spec.openapis.org/oas/v3.1.0.html

Demonstrates how to define examples for a request body's content, including multiple examples for JSON and using `externalValue` for XML and plain text.

```APIDOC
## Example Object in Request Body

### Content Examples

#### application/json
- **foo** - Summary: A foo example
  - Value: `{"foo": "bar"}`
- **bar** - Summary: A bar example
  - Value: `{"bar": "baz"}`

#### application/xml
- **xmlExample** - Summary: This is an example in XML
  - External Value: `https://example.org/examples/address-example.xml`

#### text/plain
- **textExample** - Summary: This is a text example
  - External Value: `https://foo.bar/examples/address-example.txt`
```

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

### Parameter Object Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Examples of Parameter Objects demonstrating different configurations for headers, path parameters, query parameters, and free-form query parameters.

```APIDOC
## Header Parameter Example

### Description
Example of a header parameter with an array of 64-bit integer numbers.

### Schema
```yaml
name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple
```

## Path Parameter Example

### Description
Example of a path parameter of a string value.

### Schema
```yaml
name: username
in: path
description: username to fetch
required: true
schema:
  type: string
```

## Optional Query Parameter Example

### Description
Example of an optional query parameter of a string value, allowing multiple values by repeating the query parameter.

### Schema
```yaml
name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true
```

## Free-form Query Parameter Example

### Description
Example of a free-form query parameter, allowing undefined parameters of a specific type.

### Schema
```yaml
in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form
```

## Complex Parameter with Content Example

### Description
Example of a complex parameter using `content` to define serialization for JSON.

### Schema
```yaml
in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number
```
```

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

### Example Reference in Parameter

Source: https://spec.openapis.org/oas/v3.1.0.html

Reference an example for a parameter using the '$ref' keyword. Ensure the referenced example is defined elsewhere in the specification.

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

```

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

### Response Object Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Examples demonstrating different response scenarios in OpenAPI v3.1.0.

```APIDOC
## Response Object Examples

### Response of an array of a complex type

```yaml
description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'
```

### Response with a string type

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

### Plain text response with headers

```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
```

### Response with no return value

```yaml
description: object created
```
```

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

### Examples in Request Body

Source: https://spec.openapis.org/oas/v3.1.0.html

Define examples for different media types within a request body. Use 'value' for embedded examples and 'externalValue' for external references.

```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'

```

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

### OAuth Flow Object Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Example demonstrating configurations for both Implicit and Authorization Code OAuth flows.

```APIDOC
## OAuth Flow Object Example

### Description
Example demonstrating configurations for both Implicit and Authorization Code OAuth flows.

### Type
oauth2

### Flows
#### Implicit
##### Authorization URL
https://example.com/api/oauth/dialog
##### Scopes
- **write:pets**: modify pets in your account
- **read:pets**: read your pets
#### Authorization Code
##### Authorization URL
https://example.com/api/oauth/dialog
##### Token URL
https://example.com/api/oauth/token
##### Scopes
- **write:pets**: modify pets in your account
- **read:pets**: read your pets
```

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

### Request Body Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates how to define examples for a request body, including different media types.

```APIDOC
## Request Body Examples

A request body with a referenced model definition.

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

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

### Define Request Body with Examples (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Use this to define a request body with schemas and examples for multiple media types. The 'content' field maps media types to their schema and examples.

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

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

### OpenAPI Info Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Provides a complete example of the Info Object in JSON format, including title, summary, description, terms of service, contact, license, and version.

```json
{
  "title": "Sample Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is a sample 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"
}
```

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

### Reference Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

A basic example of a Reference Object in YAML format, pointing to a schema definition.

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

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

### Single Server Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines a single server with its URL and a description. Use this for basic server definitions.

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

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

### Header Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

A simple Header Object example defining a description and schema for an integer type.

```json
{
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}
```

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

### OpenAPI Info Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates the Info Object using YAML syntax, demonstrating a human-readable alternative for API metadata.

```yaml
title: Sample Pet Store App
summary: A pet store manager.
description: This is a sample 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

```

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

### Tag Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

An example of a Tag Object specifying its name and description.

```yaml
name: pet
description: Pets operations
```

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

### Header Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

A simple Header Object example defining a description and schema for an integer type.

```yaml
description: The number of allowed requests in the current period
schema:
  type: integer
```

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

### Tag Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

An example of a Tag Object specifying its name and description.

```json
{
	"name": "pet",
	"description": "Pets operations"
}
```

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

### Ambiguous Path Templating Example

Source: https://spec.openapis.org/oas/v3.1.0.html

This example highlights potentially ambiguous path templating resolution.

```plaintext
/{entity}/me
/books/{id}

```

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

### Reference Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

A basic example of a Reference Object in JSON format, pointing to a schema definition.

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

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

### OpenAPI License Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Shows a JSON example of the License Object, specifying the API's license name and identifier.

```json
{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}
```

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

### Server Object with Variables Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates using variables within a server URL for dynamic configuration.

```APIDOC
## Server Object with Variables Example

The following shows how variables can be used for a server configuration:

```json
{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}
```

```yaml
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      default: v2
```
```

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

### Single Server Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines a single server with its URL and a description in YAML format. Use this for basic server definitions.

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

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

### Example Reference in Response

Source: https://spec.openapis.org/oas/v3.1.0.html

Reference an example for a response using the '$ref' keyword. This is useful for providing predefined success or error responses.

```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'

```

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

### Single Server Object Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines a single server with its URL and a description.

```APIDOC
## Server Object Example

A single server would be described as:

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

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

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

### Relative Schema Document Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Example of a Reference Object using a relative JSON file path to reference a schema.

```json
{
  "$ref": "Pet.json"
}
```

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

### Path Templating Matching Example

Source: https://spec.openapis.org/oas/v3.1.0.html

This example illustrates path templating matching rules in OpenAPI. Concrete paths are matched before templated paths.

```plaintext
/pets/{petId}
/pets/mine

```

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

### Example: Linking User Operations

Source: https://spec.openapis.org/oas/v3.1.0.html

Demonstrates how to use `operationId` and `$request.path.id` to link a user retrieval operation to an address retrieval operation.

```APIDOC
## Example: Linking User Operations

### Description
Demonstrates how to use `operationId` and `$request.path.id` to link a user retrieval operation to an address retrieval operation.

### Request Example (Conceptual)
```yaml
paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address
```
```

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

### Relative Schema Document Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Example of a Reference Object using a relative YAML file path to reference a schema.

```yaml
$ref: Pet.yaml
```

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

### Callback Object Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Examples demonstrating the use of the Callback object to define WebHook callbacks, including dynamic URL construction and hard-coded server URLs with dynamic query parameters.

```APIDOC
## Callback Object Examples

### myCallback
This callback uses the `queryUrl` query string parameter to define the callback URL.

#### Method
POST

#### Endpoint
`{$request.query.queryUrl}`

#### Request Body
- **Callback payload** (object) - Description: Callback payload
  - Schema: `#/components/schemas/SomePayload`

#### Responses
- **200** - Description: callback successfully processed

### transactionCallback
This callback uses a hard-coded server URL with query string parameters populated from the request body.

#### Method
POST

#### Endpoint
`http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}`

#### Request Body
- **Callback payload** (object) - Description: Callback payload
  - Schema: `#/components/schemas/SomePayload`

#### Responses
- **200** - Description: callback successfully processed
```

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

### HTTP Request Example for Callback Expressions

Source: https://spec.openapis.org/oas/v3.1.0.html

This is an example HTTP POST request used to illustrate how runtime expressions in callback objects are evaluated.

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

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

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

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

### OpenAPI License Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Presents the License Object in YAML, illustrating how to define license details like name and identifier.

```yaml
name: Apache 2.0
identifier: Apache-2.0

```

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

### OpenAPI Components Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

This JSON example demonstrates the structure of the Components Object, defining reusable schemas, parameters, responses, and security schemes.

```json
"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}
```

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

### Example Media Type Definitions

Source: https://spec.openapis.org/oas/v3.1.0.html

These are examples of possible media type definitions that can be used in OpenAPI documents. They should comply with RFC6838.

```text
  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch
```

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

### OpenAPI Contact Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Demonstrates the Contact Object in YAML format, providing a clear structure for contact information.

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

```

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

### OpenAPI External Documentation Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Example of an OpenAPI External Documentation object in YAML format, used for referencing external resources.

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

```

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

### OpenAPI External Documentation Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Example of an OpenAPI External Documentation object in JSON format, used for referencing external resources.

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

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

### OpenAPI Components Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

This YAML example illustrates the structure of the Components Object, defining reusable schemas, parameters, responses, and security schemes.

```yaml
components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

```

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

### Component Object Key Examples

Source: https://spec.openapis.org/oas/v3.1.0.html

Provides examples of valid key names for objects within the Components Object in OpenAPI. Keys must adhere to the regular expression `^[a-zA-Z0-9\.\-_]+$`.

```plaintext
User
User_1
User_Name
user-name
my.org.User
```

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

### Define Request Body with Examples (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

This YAML representation defines a request body with schemas and examples for various media types, mirroring the JSON structure.

```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'
```

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

### Parameter Object: Path String Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines a path parameter named 'username' of type string.

```json
{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

```yaml
name: username
in: path
description: username to fetch
required: true
schema:
  type: string
```

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

### Paths Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines the structure for the Paths object in YAML format, outlining available endpoints and their associated HTTP methods.

```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'
```

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

### Response Object with String and Headers

Source: https://spec.openapis.org/oas/v3.1.0.html

This example shows a plain text response that also includes custom headers, such as rate limiting information.

```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
```

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

### Implicit OAuth2 Flow

Source: https://spec.openapis.org/oas/v3.1.0.html

Example configuration for the Implicit OAuth2 flow.

```APIDOC
## Implicit OAuth2 Flow

### Description
Configuration for the Implicit OAuth2 flow, including authorization URL and available scopes.

### Type
oauth2

### Flows
#### Implicit
##### Authorization URL
https://example.com/api/oauth/dialog
##### Scopes
- **write:pets**: modify pets in your account
- **read:pets**: read your pets
```

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

### Paths Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines the structure for the Paths object in JSON format, outlining available endpoints and their associated HTTP methods.

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

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

### File Uploads - Binary Content

Source: https://spec.openapis.org/oas/v3.1.0.html

Examples for handling binary file uploads, including omitting the schema for octet-stream.

```APIDOC
## File Uploads - Binary Content

OpenAPI 3.1.0 treats file uploads using the same semantics as any other schema type. The `format` keyword has no effect on content-encoding. The `contentEncoding` keyword from JSON Schema can be used for encoding specification.

### Example: PNG Image Upload

Content transferred in binary (octet-stream) may omit `schema`.

```yaml
content:
  image/png: {}
```

### Example: Arbitrary Binary File Upload

```yaml
content:
  application/octet-stream: {}
```

### Example: Base64 Encoded PNG Upload

Binary content transferred with base64 encoding.

```yaml
content:
  image/png:
    schema:
      type: string
      contentMediaType: image/png
      contentEncoding: base64
```

### Example: Request Body for File Upload

A `requestBody` for submitting a file in a `POST` operation.

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

### Example: Multiple Specific Media Types for Upload

Specific media types may be specified for upload.

```yaml
requestBody:
  content:
    image/jpeg: {}
    image/png: {}
```
```

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

### Example: Linking with Response Body Data

Source: https://spec.openapis.org/oas/v3.1.0.html

Shows how to use `$response.body` to extract data from a response to use as a parameter for a linked operation.

```APIDOC
## Example: Linking with Response Body Data

### Description
Shows how to use `$response.body` to extract data from a response to use as a parameter for a linked operation.

### Request Example (Conceptual)
```yaml
links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid
```
```

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

### Payload example for discriminator

Source: https://spec.openapis.org/oas/v3.1.0.html

A sample JSON payload demonstrating how the 'petType' property indicates which schema (e.g., 'Cat') should be used for validation.

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

```

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

### OpenAPI Operation Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates the structure of an OpenAPI Operation object in YAML format, detailing parameters, request body, and responses.

```yaml
tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       type: object
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

```

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

### Parameter Object: Header Array Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines a header parameter named 'token' that accepts an array of 64-bit integers, using the 'simple' style.

```json
{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}
```

```yaml
name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple
```

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

### Multiple Server Objects Example (YAML)

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines multiple server options in YAML format. Useful for providing different environments like development, staging, and production.

```yaml
servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server
```

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

### OpenAPI Operation Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Illustrates the structure of an OpenAPI Operation object in JSON format, detailing parameters, request body, and responses.

```json
{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}
```

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

### Non-OAuth2 Security Requirement Example

Source: https://spec.openapis.org/oas/v3.1.0.html

Example of a security requirement object for a non-OAuth2 security scheme.

```APIDOC
## Non-OAuth2 Security Requirement Example

### Description
Example of a security requirement object for a non-OAuth2 security scheme, such as an API key.

### Security Requirement
- **api_key**: []
```

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

### Multiple Server Objects Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Defines multiple server options within an OpenAPI document. Useful for providing different environments like development, staging, and production.

```json
{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}
```

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

### Server Object with Variables Example (JSON)

Source: https://spec.openapis.org/oas/v3.1.0.html

Configures a server URL with variables for dynamic substitution, allowing for flexible server configurations. The `variables` object defines the parameters and their default or enumerated values.

```json
{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}
```