# mike-oakley/openapi-pydantic architecture

> Architecture diagram of the GitHub repository mike-oakley/openapi-pydantic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mike-oakley/openapi-pydantic
- Repository: https://github.com/mike-oakley/openapi-pydantic

## Overview

##### Project type and purpose
- openapi-pydantic is an open-source Python library that provides type-safe OpenAPI 3.0 and 3.1 schema classes built on Pydantic.
- It’s not a web service or full-stack app, but a toolkit for constructing, parsing, and validating OpenAPI definitions in Python code.

##### File structure
- Top-level package: `openapi_pydantic/`
- `compat.py` – abstracts Pydantic 1 vs 2 compatibility
- `util.py` – helper functions (e.g. `PydanticSchema`, `construct_open_api_with_schema_class`)
- `v3/` – version-independent logic, including a `parser.py` and common utilities
- `v3/v3_0/` and `v3/v3_1/` – subpackages defining Pydantic models for each OpenAPI version
- Config and metadata: `pyproject.toml`, `.github/`, `.devcontainer/`
- Scripts and tests: `smokeshow.py` (demo or quick test), `tests/` covering parsing, schema validation, utility functions.

##### README for additional insights
- Public API:
- `parse_obj()` or `OpenAPI.model_validate()` entrypoints
- `OpenAPI`, `PathItem`, `Operation`, `Response`, plus versioned imports
- Features: support for both Pydantic v1 & v2, both OpenAPI 3.0.x and 3.1.1
- Emphasis on utility functions and best practices when serializing (aliases, exclude_none).

##### Essential elements
- Clear labels for each package and module
- Callouts for important classes (`OpenAPI`, `PathItem`, `Operation`) and helpers (`PydanticSchema`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External/User
    User["User Code"]:::external

    %% Public Facade Layer
    subgraph "Public Façade" 
        Facade["Public Façade\n(openapi_pydantic/__init__.py)"]:::façade
    end

    %% Core Layer: Parser & Utilities
    subgraph "Core Parser & Utilities" 
        Parser["Versioned Parser\n(openapi_pydantic/v3/parser.py)"]:::core
        CoreUtil["Core Utilities\n(openapi_pydantic/util.py)"]:::core
        Compat["Compatibility Layer\n(openapi_pydantic/compat.py)"]:::core
        V3Util["Common v3 Utilities\n(openapi_pydantic/v3/v3_0/util.py)"]:::core
    end

    %% Schema Modules
    subgraph "Schema Modules (Orange)" 
        subgraph "OpenAPI 3.0"
            v3_0["OpenAPI 3.0 Schema\n(openapi_pydantic/v3/v3_0/)"]:::schema
        end
        subgraph "OpenAPI 3.1"
            v3_1["OpenAPI 3.1 Schema\n(openapi_pydantic/v3/v3_1/)"]:::schema
        end
    end

    %% Demo, Tests & CI
    Smoke["Smoke-Show Demo\n(smokeshow.py)"]:::external
    Tests["Test Suite\n(tests/)"]:::tests
    CI["CI Workflows\n(.github/workflows/)"]:::tests

    %% Relationships
    User -->|"parse_obj() / OpenAPI.model_validate()"| Facade
    Smoke --> Facade
    Facade -->|"delegates to"| Parser
    Facade -->|"uses helpers"| CoreUtil

    Parser -->|"dispatch based on version"| v3_0
    Parser -->|"dispatch based on version"| v3_1
    Parser --> V3Util

    CoreUtil --> V3Util
    Compat --> CoreUtil
    Compat --> Parser
    Compat --> V3Util
    Compat --> v3_0
    Compat --> v3_1

    Tests --> Facade
    Tests --> Parser
    Tests --> CoreUtil
    Tests --> v3_0
    Tests --> v3_1
    CI --> Tests

    %% Click Events
    click Facade "https://github.com/mike-oakley/openapi-pydantic/blob/main/openapi_pydantic/__init__.py"
    click Compat "https://github.com/mike-oakley/openapi-pydantic/blob/main/openapi_pydantic/compat.py"
    click CoreUtil "https://github.com/mike-oakley/openapi-pydantic/blob/main/openapi_pydantic/util.py"
    click Parser "https://github.com/mike-oakley/openapi-pydantic/blob/main/openapi_pydantic/v3/parser.py"
    click V3Util "https://github.com/mike-oakley/openapi-pydantic/blob/main/openapi_pydantic/v3/v3_0/util.py"
    click v3_0 "https://github.com/mike-oakley/openapi-pydantic/tree/main/openapi_pydantic/v3/v3_0/"
    click v3_1 "https://github.com/mike-oakley/openapi-pydantic/tree/main/openapi_pydantic/v3/v3_1/"
    click Smoke "https://github.com/mike-oakley/openapi-pydantic/blob/main/smokeshow.py"
    click Tests "https://github.com/mike-oakley/openapi-pydantic/tree/main/tests/"
    click CI "https://github.com/mike-oakley/openapi-pydantic/tree/main/.github/workflows/"

    %% Styles
    classDef external fill:#D5D5FF,stroke:#666,stroke-width:1px
    classDef façade fill:#CFE2F3,stroke:#666,stroke-width:1px
    classDef core fill:#D9EAD3,stroke:#666,stroke-width:1px
    classDef schema fill:#FCE5CD,stroke:#666,stroke-width:1px
    classDef tests fill:#E0E0E0,stroke:#666,stroke-width:1px
```
