### Multiple Server Objects Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example demonstrating how to describe multiple servers for an API.

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

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

### Media Type Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples of how to define media type examples for JSON and YAML content.

```APIDOC
## Media Type Examples

### JSON Example
```json
{
  "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 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"
```
```

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

### Install openapi-python-client with pip

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/README.md

Standard installation using pip. If you use `pipx run`, post-generation hooks will not be available unless installed manually.

```bash
pip install openapi-python-client
```

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

### Parameter Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples can be referenced for parameters, allowing for predefined values to be shown.

```APIDOC
## Parameter Examples

Examples can be provided for parameters, either directly or by reference.

### Query Parameter Example

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

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

### Paths Object Example in YAML

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

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

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

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

### Path Item Object Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

An example demonstrating the structure of a Path Item Object, which includes details for HTTP methods like GET and associated parameters.

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

### Description
Returns pets based on ID.

### Method
GET

### Endpoint
/pets/{id}

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

### Response
#### Success Response (200)
- **items** (array[Pet]) - pet response

#### Error Response (default)
- **schema** (ErrorModel) - error payload
```

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

### Reference Example for Response

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example for a successful response can be referenced using '$ref' to an existing example object.

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

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

### Reference Example for Query Parameter

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example for a query parameter can be defined by referencing an existing example object using '$ref'.

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

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

### Object with Example Data

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Include an example of the object's structure and data. This aids in understanding and testing.

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

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

### Model with Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Defines an object model with properties and an example value. The example helps illustrate the expected data structure.

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

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

### Model with Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Defines an object model with properties and an example value. The example helps illustrate the expected data structure.

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

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

### YAML Media Type Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples of defining media types with inline and referenced examples in YAML format.

```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 Parameter Example (String)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a path parameter named 'username' which is a string. It is marked as required.

```APIDOC
## Path Parameter: username

### Description
This is a path parameter named 'username' that accepts a string value. It is required for the request.

### In
path

### Required
true

### Schema
```json
{
  "type": "string"
}
```
```

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

### Response Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples can be defined for successful responses to illustrate expected output.

```APIDOC
## Response Examples

Examples can be defined for responses to illustrate successful outcomes.

### Success Response Example

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

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

### JSON Media Type Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples of defining media types with inline and referenced examples in JSON format.

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

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

### Server Object with Variables Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a Server object utilizing variables for URL templating and 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:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2
```

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

### Parameter Object Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Examples demonstrating different types of parameters including header, path, and query parameters with various schema configurations.

```APIDOC
## Header Parameter with Array of Integers

### Description
Example of a header parameter named 'token' that accepts an array of 64-bit integers.

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

```APIDOC
## Path Parameter with String Value

### Description
Example of a path parameter named 'username' for fetching user-specific data.

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

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

```APIDOC
## Optional Query Parameter with Array of Strings

### Description
Example of an optional query parameter 'id' that can accept multiple string values by repeating the parameter.

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

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

```APIDOC
## Free-form Query Parameter

### Description
Example of a free-form query parameter 'freeForm' that allows undefined parameters of a specific integer type.

### Schema
```json
{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    }
  },
  "style": "form"
}
```

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

```APIDOC
## Complex Query Parameter with Content Definition

### Description
Example of a query parameter 'coordinates' using the 'content' object to define its JSON schema, requiring 'lat' and 'long' properties.

### Schema
```json
{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}
```

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

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

### Install openapi-python-client with pipx

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/README.md

Recommended installation using pipx to avoid package conflicts. Includes the `--include-deps` option to make `ruff` available for code cleanup.

```bash
pipx install openapi-python-client --include-deps
```

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

### Build and Install Local Wheel

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/literal-enums-golden-record/README.md

Build a wheel file for the OpenAPI Python client and install it using pip. This is for projects not managed by Poetry.

```bash
poetry build -f wheel
```

```bash
pip install <path-to-wheel>
```

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

### License Object Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a License object specifying the license information for the API.

```json
{
  "name": "Apache 2.0",
  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}
```

```yaml
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
```

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

### Primitive Schema Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a primitive schema definition in YAML format.

```yaml
type: string
format: email
```

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

### Header Parameter Example (Array of int64)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a header parameter named 'token' which is an array of 64-bit integers. It is marked as required.

```APIDOC
## Header Parameter: token

### Description
This is a header parameter named 'token' that accepts an array of 64-bit integers. It is required for the request.

### In
header

### Required
true

### Schema
```json
{
  "type": "array",
  "items": {
    "type": "integer",
    "format": "int64"
  }
}
```

### Style
simple
```

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

### Single Server Object Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a Server object defining a single server for the API.

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

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

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

### Example Object

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Defines the structure and usage of the Example Object in OpenAPI, including fixed fields like summary, description, value, and externalValue, along with examples of its application in request bodies, parameters, and responses.

```APIDOC
#### <a name="exampleObject"></a>Example Object

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="exampleSummary"></a>summary | `string` | Short description for the example.
<a name="exampleDescription"></a>description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
<a name="exampleExternalValue"></a>externalValue | `string` | A URI that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. See the rules for resolving [Relative References](#relativeReferencesURI).

This object MAY be extended with [Specification Extensions](#specificationExtensions).

In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

##### Example Object Examples

In a request body:

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

In a parameter:

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

In a response:

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

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

### Response Object Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples demonstrating various configurations of the Response Object, including responses with arrays, strings, headers, and no return values.

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

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

### Relative Schema Document Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a Reference Object pointing to a relative schema document in JSON.

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

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

### Paths Object Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

An example illustrating the structure of the Paths Object, showing how paths are mapped to HTTP methods and their respective operations.

```APIDOC
## Paths Object Example

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

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

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

### Example Object in Request Body

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Define examples for JSON, XML, and plain text content types within a request body.

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

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

### External Documentation Object Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example of an External Documentation object in YAML format, linking to additional information.

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

```

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

### External Documentation Object Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example of an External Documentation object in JSON format, linking to additional information.

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

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

### Server Variable Field Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples of valid keys for server variables. These keys must match the regular expression ^[a-zA-Z0-9\.\-_]+$.

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

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

### Response Object Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Examples demonstrating various response types including arrays of complex objects, simple strings, and responses with headers.

```APIDOC
## Response Object Examples

### Response Object: Array of Complex Type

This example shows a response containing an array of a complex type, referencing `#/components/schemas/VeryComplexType`.

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

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

### Response Object: String Type

This example defines a response with a simple string type.

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

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

### Response Object: Plain Text with Headers

This example illustrates a plain text response that includes rate limiting headers.

#### JSON Example
```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 Example
```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 Object: No Return Value

This example shows a response indicating an object was created, with no specific return value defined.

#### JSON Example
```json
{
  "description": "object created"
}
```

#### YAML Example
```yaml
description: object created
```
```

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

### Simple Model Schema Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a simple object schema definition with properties and required fields in YAML format.

```yaml
type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0
```

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

### Install Wheel in Non-Poetry Project

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/docstrings-on-attributes-golden-record/README.md

Install the built wheel file of the OpenAPI client into a project that is not managed by Poetry. This allows using the client in standard Python environments.

```bash
pip install <path-to-wheel>
```

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

### Request Body Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Examples can be provided for different media types within a request body. This includes JSON, XML, and plain text.

```APIDOC
## Request Body Examples

Examples can be defined for various media types within the `requestBody` object.

### JSON Example

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

### XML Example

```yaml
requestBody:
  content:
    'application/xml':
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: 'http://example.org/examples/address-example.xml'
```

### Plain Text Example

```yaml
requestBody:
  content:
    'text/plain':
      examples:
        textExample:
          summary: This is a text example
          externalValue: 'http://foo.bar/examples/address-example.txt'
```
```

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

### HTTP Request Example for Callback Expressions

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Illustrates an incoming HTTP POST request used to evaluate callback expressions. This example shows the structure of the request body and headers.

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

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

### Callback Object Examples

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Examples demonstrating the use of callback objects to define WebHook callbacks, including dynamic URL construction and hard-coded server URLs with request body parameter population.

```APIDOC
## Callback Object Examples

The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook.

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

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

### OpenAPI Components Object Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

An example of the Components object in YAML format, illustrating 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
```

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

### Generate Client with Setup.py

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/README.md

Generates a client library with a setup.py file instead of pyproject.toml.

```bash
openapi-python-client generate --meta=setup
```

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

### OpenAPI Components Object Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

An example of the Components object in JSON format, illustrating 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"
          }
        }
      }
    }
  }
}
```

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

### Paths Object Example in JSON

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

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

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

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

### Client Initialization

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/test-3-1-golden-record/README.md

Demonstrates how to create a basic client instance and an authenticated client instance.

```APIDOC
## Client Initialization

### Description
Initialize the client library for accessing the Test 3.1 Features API. Use `Client` for unauthenticated access and `AuthenticatedClient` for requests requiring a token.

### Usage

```python
from test_3_1_features_client import Client, AuthenticatedClient

# Basic client
client = Client(base_url="https://api.example.com")

# Authenticated client
client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
```
```

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

### OpenAPI 3.0.3 Components Object Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example of the Components Object in YAML format, demonstrating reusable definitions for 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: http://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets
```

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

### Path Item Object Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example of a Path Item Object in OpenAPI 3.0.3, demonstrating a GET operation to retrieve pets by ID.

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

### Description
Returns pets based on ID.

### Method
GET

### Endpoint
/pets/{id}

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

### Response
#### Success Response (200)
- **array[Pet]** - pet response

#### Error Response (default)
- **ErrorModel** - error payload
```

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

### Client Initialization

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/golden-record/README.md

Demonstrates how to create a basic client instance and an authenticated client instance with a token.

```APIDOC
## Client Initialization

### Description
Initialize the client library for accessing the API. Use `Client` for unauthenticated requests and `AuthenticatedClient` for requests requiring authentication.

### Usage

**Unauthenticated Client:**
```python
from my_test_api_client import Client

client = Client(base_url="https://api.example.com")
```

**Authenticated Client:**
```python
from my_test_api_client import AuthenticatedClient

client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
```
```

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

### Client Initialization

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/docstrings-on-attributes-golden-record/README.md

Demonstrates how to create a basic client instance and an authenticated client instance with token-based authentication.

```APIDOC
## Client Initialization

### Description
Initialize the client with the base URL of the API. For authenticated requests, use `AuthenticatedClient` with a token.

### Usage
```python
from my_test_api_client import Client, AuthenticatedClient

# Basic client
client = Client(base_url="https://api.example.com")

# Authenticated client
client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
```
```

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

### Initialize Basic Client

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/docstrings-on-attributes-golden-record/README.md

Create a client instance for accessing the API. No authentication is required for this basic setup.

```python
from my_test_api_client import Client

client = Client(base_url="https://api.example.com")
```

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

### Make Synchronous API Calls

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/test-3-1-golden-record/README.md

Call API endpoints using the synchronous client. This example shows how to fetch data and how to get detailed response information including status codes.

```python
from test_3_1_features_client.models import MyDataModel
from test_3_1_features_client.api.my_tag import get_my_data_model
from test_3_1_features_client.types import Response

with client as client:
    my_data: MyDataModel = get_my_data_model.sync(client=client)
    # or if you need more info (e.g. status_code)
    response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
```

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

### Create a Basic Client

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/literal-enums-golden-record/README.md

Instantiate the client with the base URL of the API. This is the starting point for all API interactions.

```python
from my_enum_api_client import Client

client = Client(base_url="https://api.example.com")
```

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

### Create a Basic Client

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/integration-tests/README.md

Instantiate the client with the base URL of the API. This is the starting point for all API interactions.

```python
from integration_tests import Client

client = Client(base_url="https://api.example.com")
```

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

### Instantiate a Basic Client

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/end_to_end_tests/test-3-1-golden-record/README.md

Create a client instance for making API requests. Ensure the `base_url` is correctly set.

```python
from test_3_1_features_client import Client

client = Client(base_url="https://api.example.com")
```

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

### Server Object with Variables Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Demonstrates server URL templating with variables in YAML, showing default values, enums, and descriptions.

```yaml
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2
```

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

### Server Object with Variables Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Illustrates using variables within a server URL for dynamic configuration, including default values and enums.

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

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

### Single Server Object Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Defines a single server with its URL and an optional description.

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

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

### Primitive Schema Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Example of a primitive schema definition in JSON format.

```json
{
  "type": "string",
  "format": "email"
}
```

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

### Multiple Server Objects Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Describes how to define multiple servers for an API, allowing clients to connect to different environments.

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

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

### Single Server Object Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Defines a single server with its URL and an optional description in YAML format.

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

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

### Operation Object Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

An example of the Operation object, which describes a single API operation on a path.

```APIDOC
## POST /pet/{petId}

### Description
Updates a pet in the store with form data.

### Method
POST

### Endpoint
/pet/{petId}

### Parameters
#### Path Parameters
- **petId** (string) - Required - ID of pet that needs to be updated

#### Request Body
- **name** (string) - Optional - Updated name of the pet
- **status** (string) - Required - Updated status of the pet

### Response
#### Success Response (200)
- Description: Pet updated.

#### Error Response (405)
- Description: Method Not Allowed
```

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

### Multiple Server Objects Example (YAML)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.1.0.md

Describes how to define multiple servers for an API in YAML format.

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

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

### Info Object Example (JSON)

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Provides metadata about the API, including title, description, terms of service, contact information, license, and version.

```json
{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://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"
}
```

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

### Path Templating Matching Example

Source: https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/schema/3.0.3.md

Illustrates path matching rules in OpenAPI, showing how concrete paths are prioritized over templated paths and identifying invalid or ambiguous path definitions.

```yaml
  /pets/{petId}
  /pets/mine
```