# getkin/kin-openapi architecture

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

- Interactive diagram: https://gitdiagram.com/getkin/kin-openapi
- Repository: https://github.com/getkin/kin-openapi

## Overview

##### Project type and purpose
- This is an open-source Go library plus a small CLI (cmd/validate) for working with OpenAPI specs:
- Parsing, serializing and validating OpenAPI v2 (Swagger) files
- Converting v2 → v3 (openapi2conv)
- Parsing, serializing and validating OpenAPI v3 (openapi3)
- Validating HTTP requests/responses against a v3 spec and providing router middleware (openapi3filter + routers/gorillamux, routers/legacy)
- Generating OpenAPI 3 Schema objects from Go types (openapi3gen)

##### File structure and infer architectural components
- Top-level “cmd”: the CLI entrypoint (`cmd/validate/main.go`)
- Core libraries/packages (each in its own directory):
- openapi2: v2 file model, (de)serialization, validation
- openapi2conv: converter from v2 → v3
- openapi3: v3 file model, (de)serialization, validation
- openapi3filter: HTTP request/response validation, middleware, error handling
- openapi3gen: schema generator for Go types
- Router implementations under routers/ (gorillamux and legacy pathpattern)
- Support files: tests (deep coverage), GitHub workflows, docs (openapi-.txt), helper scripts (docs.sh, maps.sh)

##### Key relationships and flow
- CLI or user’s Go application → uses openapi3.Loader to load spec (JSON/YAML)
- openapi3.Loader resolves $ref → yields in-memory `*openapi3.T`
- Optionally: openapi2conv converts a v2 `*openapi2.T` to a v3 doc
- Spec is validated (`doc.Validate()`)
- Router is instantiated (e.g. gorillamux.NewRouter(doc)) → maps HTTP requests → OpenAPI Operation
- openapi3filter.ValidateRequest / ValidateResponse applied around user handler
- openapi3gen invoked by user code or codegen tools to produce schema definitions from Go structs/types

##### Architectural patterns and principles
- Layered design:
Layer 1: Spec parsing & model (openapi2, openapi3)
Layer 2: Conversion (openapi2conv)
Layer 3: Validation (model.Validate, openapi3filter)
Layer 4: Routing (routers/*)
Layer 5: Codegen (openapi3gen)
- Separation of concerns: each package has a single responsibility
- Plugin/extension points: custom body decoders, custom uniqueness checkers, custom error messaging in openapi3filter

##### Final checklist
- All major packages shown as distinct components
- Spec load path
- Conversion path
- Validation and routing path
- Codegen path
- External dependencies clearly marked
- Annotation of extension points (e.g., “RegisterBodyDecoder here”)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "CLI"
        CLI["CLI Tool (cmd/validate)"]:::cli
    end

    subgraph "Spec Parsing & Modeling"
        OAP2["openapi2 (v2 model)"]:::parsing
        OAP3["openapi3 (v3 model)"]:::parsing
    end

    subgraph "Conversion"
        Conv["openapi2conv"]:::parsing
    end

    subgraph "Validation"
        Filter["openapi3filter"]:::validation
    end

    subgraph "Routing"
        GMux["routers/gorillamux"]:::routing
        Legacy["routers/legacy"]:::routing
    end

    subgraph "Codegen"
        Gen["openapi3gen"]:::codegen
    end

    subgraph "External Dependencies"
        HTTP["net/http"]:::external
        Gorilla["gorilla/mux"]:::external
        UserApp["User Application"]:::external
    end

    CLI -->|"load v2 spec"| OAP2
    CLI -->|"load v3 spec"| OAP3

    OAP2 -->|"convert v2→v3"| Conv
    Conv -->|"produces v3 *T"| OAP3

    OAP3 -->|"instantiate router"| GMux
    OAP3 -->|"instantiate router"| Legacy

    GMux -->|"wrap with middleware"| Filter
    Legacy -->|"wrap with middleware"| Filter

    Filter --> HTTP
    Filter --> Gorilla

    UserApp --> GMux
    UserApp --> Legacy
    UserApp -->|"uses middleware"| Filter

    UserApp -->|"generate schema"| Gen

    click CLI "https://github.com/getkin/kin-openapi/blob/master/cmd/validate/main.go"
    click OAP2 "https://github.com/getkin/kin-openapi/tree/master/openapi2/"
    click Conv "https://github.com/getkin/kin-openapi/blob/master/openapi2conv/openapi2_conv.go"
    click OAP3 "https://github.com/getkin/kin-openapi/tree/master/openapi3/"
    click Filter "https://github.com/getkin/kin-openapi/tree/master/openapi3filter/"
    click GMux "https://github.com/getkin/kin-openapi/blob/master/routers/gorillamux/router.go"
    click Legacy "https://github.com/getkin/kin-openapi/blob/master/routers/legacy/router.go"
    click Gen "https://github.com/getkin/kin-openapi/blob/master/openapi3gen/openapi3gen.go"

    classDef cli fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef parsing fill:#D6EAF8,stroke:#3498DB,color:#154360;
    classDef validation fill:#D5F5E3,stroke:#28B463,color:#1D8348;
    classDef routing fill:#FAD7A0,stroke:#EB984E,color:#7E5109;
    classDef codegen fill:#E8DAEF,stroke:#9B59B6,color:#4A235A;
    classDef external fill:#F2F3F4,stroke:#BFC9CA,color:#566573;
```
