How getkin/kin-openapi works
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”)