# kubernetes/kube-openapi architecture

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

- Interactive diagram: https://gitdiagram.com/kubernetes/kube-openapi
- Repository: https://github.com/kubernetes/kube-openapi

## Overview

##### Project type and purpose
- This is a Go-based CLI tool (“Kube OpenAPI”) that discovers and generates OpenAPI specs for Kubernetes-style APIs.
- It consists of two main functional areas outlined in the README:
- Model generator: parses Go source to extract type definitions.
- Spec generator: combines routes or existing JSON/YAML specs into a final OpenAPI document.
- There are two CLI front-ends: openapi-gen and openapi2smd, plus conversion subcommands and test harnesses under cmd/.

##### File structure
- cmd/…: entrypoints (openapi-gen, openapi2smd).
- pkg/…: the heart of the tool, split into subpackages:
- aggregator: merges multiple OpenAPI fragments
- builder & builder3: turn Go AST/markers into schema definitions
- handler & handler3: HTTP/webservice route introspection
- generators: lints, enforces rules, emits JSON/YAML
- openapiconv, schemaconv, schemamutation: convert between spec versions, mutate schemas
- spec3: in-memory representation of OpenAPI v3
- validation: verify schema/JSON conformance
- util & cached & common: shared abstractions, caching, JSON adapter, RESTful route adapter
- internal/third_party: vendored JSON and validator libraries
- hack/: scripts to update libraries
- test/ & pkg/*_test.go: unit and integration tests

##### Key interactions & dependencies (from README + imports)
- CLI layer (cmd/) invokes:
- Model generation: builder → handler → spec3 models
- Aggregation: aggregator walks spec fragments
- Conversion: openapiconv, schemaconv
- Validation: validation packages run post-generation checks
- Utilities provide JSON serialization/parsing and caching.
- Third-party libs live in internal/third_party and feed into JSON marshalling.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        OG["openapi-gen"]:::cli
        O2S["openapi2smd"]:::cli
    end

    %% Model Generator Pipeline
    subgraph "Model Generator Pipeline"
        direction TB
        H2["Go AST Parser (handler/handler.go, handler3)"]:::core
        MP["Marker Extractor (common, generators)"]:::core
        SB2["Schema Builder v2 (builder)"]:::core
        SB3["Schema Builder v3 (builder3)"]:::core
        SM["spec3 In-memory Model"]:::data
    end

    %% Spec Generation & Aggregation
    subgraph "Spec Generator & Aggregation"
        direction TB
        AGG["Aggregator"]:::core
        GEN["Spec Generators & Linting"]:::core
        CONV["Converters (openapiconv, schemaconv, schemamutation)"]:::core
    end

    %% Validation Layer
    subgraph "Validation Layer"
        direction TB
        VAL_SPEC["Spec Validators"]:::validation
        VAL_ERR["Error Definitions"]:::validation
        VAL_FMT["Format Validators"]:::validation
        VAL_JSON["JSON Schema Engine"]:::validation
    end

    %% Utilities & Third-Party
    subgraph "Utilities & Third-Party"
        direction TB
        JSON_LIB["JSON Library (go-json-experiment)"]:::util
        CACHE["Caching Layer"]:::util
        REST_ADP["RESTful Adapter"]:::util
        HELP["General Helpers"]:::util
    end

    %% Output
    OUTPUT["OpenAPI JSON/YAML Output"]:::data

    %% Data Flows
    OG -->|invokes| H2
    O2S -->|invokes| H2
    H2 -->|extracts markers| MP
    MP -->|builds schemas| SB2
    SB2 -->|produces| SM
    MP -->|builds schemas| SB3
    SB3 -->|produces| SM
    SM -->|feeds| AGG
    AGG -->|passes fragments| GEN
    GEN -->|calls| CONV
    CONV -->|yields specs| VAL_SPEC
    VAL_SPEC --> VAL_ERR
    VAL_SPEC --> VAL_FMT
    VAL_FMT --> VAL_JSON
    VAL_JSON -->|validated specs| JSON_LIB
    JSON_LIB -->|serializes| OUTPUT

    %% Utilities usage
    CACHE -.-> SB2
    CACHE -.-> SB3
    REST_ADP -.-> H2
    HELP -.-> MP
    JSON_LIB -.-> VAL_JSON

    %% Click Events
    click OG "https://github.com/kubernetes/kube-openapi/blob/master/cmd/openapi-gen/openapi-gen.go"
    click O2S "https://github.com/kubernetes/kube-openapi/blob/master/cmd/openapi2smd/openapi2smd.go"
    click H2 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/handler/handler.go"
    click H2 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/handler3/handler.go"
    click H2 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/handler/default_pruning.go"
    click MP "https://github.com/kubernetes/kube-openapi/blob/master/pkg/common/common.go"
    click REST_ADP "https://github.com/kubernetes/kube-openapi/blob/master/pkg/common/restfuladapter/adapter.go"
    click SB2 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/builder/openapi.go"
    click SB2 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/builder/parameters.go"
    click SB3 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/builder3/openapi.go"
    click SB3 "https://github.com/kubernetes/kube-openapi/blob/master/pkg/builder3/util/util.go"
    click SM "https://github.com/kubernetes/kube-openapi/blob/master/pkg/spec3/spec.go"
    click SM "https://github.com/kubernetes/kube-openapi/blob/master/pkg/spec3/component.go"
    click SM "https://github.com/kubernetes/kube-openapi/blob/master/pkg/spec3/path.go"
    click AGG "https://github.com/kubernetes/kube-openapi/blob/master/pkg/aggregator/aggregator.go"
    click AGG "https://github.com/kubernetes/kube-openapi/blob/master/pkg/aggregator/walker.go"
    click GEN "https://github.com/kubernetes/kube-openapi/blob/master/pkg/generators/openapi.go"
    click GEN "https://github.com/kubernetes/kube-openapi/blob/master/pkg/generators/api_linter.go"
    click CONV "https://github.com/kubernetes/kube-openapi/blob/master/pkg/openapiconv/convert.go"
    click CONV "https://github.com/kubernetes/kube-openapi/blob/master/pkg/schemaconv/openapi.go"
    click CONV "https://github.com/kubernetes/kube-openapi/blob/master/pkg/schemamutation/walker.go"
    click VAL_SPEC "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/spec/contact_info.go"
    click VAL_SPEC "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/spec/path_item.go"
    click VAL_ERR "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/errors/api.go"
    click VAL_FMT "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/strfmt/date.go"
    click VAL_FMT "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/strfmt/duration.go"
    click VAL_JSON "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/validate/validator.go"
    click VAL_JSON "https://github.com/kubernetes/kube-openapi/blob/master/pkg/validation/validate/schema.go"
    click JSON_LIB "https://github.com/kubernetes/kube-openapi/blob/master/pkg/internal/third_party/go-json-experiment/json/encode.go"
    click JSON_LIB "https://github.com/kubernetes/kube-openapi/blob/master/pkg/internal/third_party/go-json-experiment/json/decode.go"
    click CACHE "https://github.com/kubernetes/kube-openapi/blob/master/pkg/cached/cache.go"
    click HELP "https://github.com/kubernetes/kube-openapi/blob/master/pkg/util/util.go"
    click HELP "https://github.com/kubernetes/kube-openapi/blob/master/pkg/util/jsontesting/json_roundtrip.go"

    %% Styles
    classDef cli fill:#B3E5FC,stroke:#0288D1,color:#000
    classDef core fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef validation fill:#FFCDD2,stroke:#D32F2F,color:#000
    classDef util fill:#D1C4E9,stroke:#7B1FA2,color:#000
    classDef data fill:#FFF9C4,stroke:#FBC02D,color:#000
```
