openapi-python-client

The functional_tests module contains end-to-end tests that treat both the generator and the generated code as black boxes. Instead of testing low-level implementation details or comparing code against 'golden records', these tests verify the actual behavior of the generated client at runtime.

There are two primary submodules:

1. generated_code_execution: Uses valid API specs to run the generator, then imports and executes the resulting code to ensure it works correctly.
2. generator_failure_cases: Uses invalid API specs to verify that the generator correctly produces warnings for bad schemas or fatal errors for invalid specifications.

Runtime expressions allow you to define values based on information available during an actual HTTP call. These are primarily used within Link Objects and Callback Objects to dynamically drive operations.

Key rules:

• Expressions preserve the type of the referenced value.
• Expressions can be embedded into string values by surrounding them with {} curly braces.
• If a runtime expression fails to evaluate, no parameter value is passed to the target operation.
• Request parameters (like headers or path params) MUST be declared in the parameters section of the parent operation to be evaluatable.

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

When defining arrays in XML, you can control whether they are wrapped in a container element or appear as a sequence of elements.

• Unwrapped (Default): Elements appear one after another. To give them a specific name, use xml.name inside the items object.
• Wrapped: Elements are contained within a parent element. To control the parent element name, use xml.name on the array itself. To control the child element name, use xml.name inside the items object.

Example of a wrapped array with custom names:

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

Resulting XML: <aliens><animal>value</animal></aliens>

In an OpenAPI specification, a parameter's location is defined by the in field. There are four possible values:

• path: The parameter is part of the operation's URL (e.g., /items/{itemId}). If in is path, the required property MUST be true.
• query: Parameters appended to the URL (e.g., /items?id=123).
• header: Custom HTTP headers. Note that Accept, Content-Type, and Authorization headers should be ignored if defined here.
• cookie: Used to pass specific cookie values to the API.

The OpenAPI Specification (OAS) is a language-agnostic standard for defining HTTP APIs. It allows both humans and machines to discover and understand an API's capabilities (endpoints, parameters, request/response formats) without needing access to the source code.

When using openapi-python-client, you provide an OpenAPI definition (typically a YAML or JSON file) which the tool then uses to generate a type-safe Python client. The quality and completeness of your generated client depend on how well your OpenAPI definition adheres to the specification.

Some OpenAPI schema types cannot be implemented as standard Pydantic models due to Python's typing constraints regarding dynamic field names. These types are implemented as type aliases for Dict.

When you need to create instances of these types, do not attempt to use a class constructor; instead, use a standard Python dict.

Supported types implemented as Dict:

• Callback: Dict[str, PathItem]
• Paths: Dict[str, PathItem]
• Responses: Dict[str, Union[Response, Reference]]
• SecurityRequirement: Dict[str, List[str]]

The generator maps every path/method combination to a Python module.

Module Location:

• If an endpoint has tags, the first tag is used as the module name (e.g., my_enum_api_client.api.my_tag).
• If an endpoint has no tags, it is located in my_enum_api_client.api.default.

Available Functions per Module: Each endpoint module provides four distinct functions:

1. sync: A blocking request that returns the parsed data model if successful, or None if it fails.
2. sync_detailed: A blocking request that returns a Response[Model] object, which includes the parsed data and metadata like status_code.
3. asyncio: An asynchronous version of sync.
4. asyncio_detailed: An asynchronous version of sync_detailed.

All path parameters, query parameters, and request bodies are exposed as arguments to these functions.

OpenAPI allows the use of runtime expressions to reference dynamic values during operation execution. Expressions can be embedded into string values by surrounding them with {} curly braces. Note that runtime expressions preserve the type of the referenced value.

Common expression patterns include:

• HTTP Method: $method (the allowable values are the HTTP operation methods).
• Requested media type: $request.header.accept.
• Request parameter: $request.path.id (Note: parameters MUST be declared in the parameters section of the parent operation to be evaluated).
• Request body property: $request.body#/user/uuid (references portions of the requestBody).
• Request URL: $url.
• Response value: $response.body#/status (references portions of the response body).
• Response header: $response.header.Server (only single header values are available).