Loader

openapi_first.loader

Summary

OpenAPI specification loading and validation utilities.

This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.

It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.

Notes

Design Principles:

- OpenAPI is treated as an authoritative contract.
- Invalid specifications fail fast at application startup.
- Supported formats are JSON and YAML.
- Validation errors are surfaced clearly and early.

Constraints:

- This module intentionally does NOT:
    - Modify the OpenAPI document.
    - Infer missing fields.
    - Generate models or code.
    - Perform request/response validation at runtime.

Classes

OpenAPISpecLoadError

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

Notes

Guarantees:

- This error indicates that the OpenAPI document is unreadable,
  malformed, or violates the OpenAPI 3.x specification.

Functions

load_openapi

load_openapi(path: Union[str, Path]) -> Dict[str, Any]

Load and validate an OpenAPI 3.x specification from disk.

Parameters:

Name	Type	Description	Default
path	str | Path	Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.	required

Returns:

Type	Description
Dict[str, Any]	dict[str, Any]: Parsed and validated OpenAPI specification.

Raises:

Type	Description
OpenAPISpecLoadError	If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.

Notes

Guarantees:

- The specification is parsed based on file extension and validated
  using a strict OpenAPI schema validator.
- Any error results in an immediate exception, preventing
  application startup.