# oaswrap/spec architecture

> Architecture diagram of the GitHub repository oaswrap/spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oaswrap/spec
- Repository: https://github.com/oaswrap/spec

## Overview

oaswrap/spec is a code-first Go library for registering HTTP routes and generating validated OpenAPI documents, with framework adapters and optional documentation UI wiring. The principal workflow is route and typed-option registration, schema reflection from Go types, document construction, validation, then JSON/YAML output. The README documents additional version-specific operations, webhooks, security and customization hooks. Adapter source excerpts are partial, so framework adapters are represented collectively; uncertain internal call wiring is omitted.

Main entry points: [`router.go`](https://github.com/oaswrap/spec/blob/main/router.go) (Core router), [`openapi`](https://github.com/oaswrap/spec/tree/main/openapi) (OpenAPI model), [`adapter`](https://github.com/oaswrap/spec/tree/main/adapter) (Framework adapters), [`internal/builder`](https://github.com/oaswrap/spec/tree/main/internal/builder) (Document builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Route entry points"]
  node_adapters["Framework adapters"]
  node_router["Core router<br/>[router.go]"]
  node_options["Typed options"]
  node_paramparser["Path parser"]
  node_uiintegration["Adapter docs wiring"]
end

subgraph group_core["Generation core"]
  node_builder["Document builder"]
  node_webhooks["Webhook operations<br/>[router.go]"]
end

subgraph group_schema["Schema and models"]
  node_reflector["Type reflector"]
  node_openapimodel["OpenAPI model"]
  node_schemafeatures["Schemas and parameters"]
  node_security["Security configuration<br/>[security.go]"]
end

subgraph group_output["Validation and output"]
  node_validator["Spec validator"]
  node_codec["JSON YAML codec<br/>[codec.go]"]
  node_specuiopts["UI option mapper<br/>[specui.go]"]
end

node_developer(("API developer"))
node_specui["Docs UI handler"]
node_documentconsumer(("Document consumer"))

node_developer -->|"registers routes"| node_adapters
node_developer -->|"registers routes"| node_router
node_developer -->|"supplies options"| node_options
node_adapters -->|"registers operations"| node_router
node_adapters -->|"parses paths"| node_paramparser
node_router -->|"adds operations"| node_builder
node_router -->|"applies configuration"| node_options
node_router -->|"adds webhooks"| node_webhooks
node_builder -->|"reflects types"| node_reflector
node_builder -->|"builds document"| node_openapimodel
node_reflector -->|"creates schemas"| node_openapimodel
node_options -->|"configures schemes"| node_security
node_security -->|"sets security"| node_openapimodel
node_webhooks -->|"adds webhook operation"| node_builder
node_router -->|"validates document"| node_validator
node_router -->|"serializes document"| node_codec
node_validator -->|"checks invariants"| node_openapimodel
node_codec -->|"returns JSON YAML"| node_documentconsumer
node_router -.->|"maps UI options"| node_specuiopts
node_adapters -.->|"wires docs routes"| node_uiintegration
node_uiintegration -.->|"serves docs UI"| node_specui
node_specuiopts -.->|"configures handler"| node_specui
node_documentconsumer -.->|"uses typed models"| node_openapimodel

click node_adapters "https://github.com/oaswrap/spec/tree/main/adapter"
click node_router "https://github.com/oaswrap/spec/blob/main/router.go"
click node_options "https://github.com/oaswrap/spec/tree/main/option"
click node_paramparser "https://github.com/oaswrap/spec/blob/main/pkg/parser/colon_param_parser.go"
click node_builder "https://github.com/oaswrap/spec/tree/main/internal/builder"
click node_reflector "https://github.com/oaswrap/spec/tree/main/internal/reflect"
click node_openapimodel "https://github.com/oaswrap/spec/tree/main/openapi"
click node_validator "https://github.com/oaswrap/spec/tree/main/internal/validate"
click node_codec "https://github.com/oaswrap/spec/blob/main/openapi/codec.go"
click node_specuiopts "https://github.com/oaswrap/spec/blob/main/internal/mapper/specui.go"
click node_schemafeatures "https://github.com/oaswrap/spec/tree/main/internal/reflect"
click node_security "https://github.com/oaswrap/spec/blob/main/option/security.go"
click node_webhooks "https://github.com/oaswrap/spec/blob/main/router.go"
click node_uiintegration "https://github.com/oaswrap/spec/tree/main/adapter"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_adapters,node_router,node_options,node_paramparser,node_uiintegration,node_specui toneBlue
class node_builder,node_webhooks toneAmber
class node_reflector,node_openapimodel,node_schemafeatures,node_security,node_developer toneMint
class node_validator,node_codec,node_specuiopts toneRose
class node_documentconsumer toneIndigo
```

## Components

### Route entry points

- [Framework adapters](https://github.com/oaswrap/spec/tree/main/adapter): `adapter`
- [Core router](https://github.com/oaswrap/spec/blob/main/router.go): `router.go`
- [Typed options](https://github.com/oaswrap/spec/tree/main/option): `option`
- [Path parser](https://github.com/oaswrap/spec/blob/main/pkg/parser/colon_param_parser.go): `pkg/parser/colon_param_parser.go`
- [Adapter docs wiring](https://github.com/oaswrap/spec/tree/main/adapter): `adapter`

### Generation core

- [Document builder](https://github.com/oaswrap/spec/tree/main/internal/builder): `internal/builder`
- [Webhook operations](https://github.com/oaswrap/spec/blob/main/router.go): `router.go`

### Schema and models

- [Type reflector](https://github.com/oaswrap/spec/tree/main/internal/reflect): `internal/reflect`
- [OpenAPI model](https://github.com/oaswrap/spec/tree/main/openapi): `openapi`
- [Schemas and parameters](https://github.com/oaswrap/spec/tree/main/internal/reflect): `internal/reflect`
- [Security configuration](https://github.com/oaswrap/spec/blob/main/option/security.go): `option/security.go`

### Validation and output

- [Spec validator](https://github.com/oaswrap/spec/tree/main/internal/validate): `internal/validate`
- [JSON YAML codec](https://github.com/oaswrap/spec/blob/main/openapi/codec.go): `openapi/codec.go`
- [UI option mapper](https://github.com/oaswrap/spec/blob/main/internal/mapper/specui.go): `internal/mapper/specui.go`

### Other components

- **API developer**
- **Docs UI handler**
- **Document consumer**

## Connections

- API developer → Framework adapters: registers routes
- API developer → Core router: registers routes
- API developer → Typed options: supplies options
- Framework adapters → Core router: registers operations
- Framework adapters → Path parser: parses paths
- Core router → Document builder: adds operations
- Core router → Typed options: applies configuration
- Core router → Webhook operations: adds webhooks
- Document builder → Type reflector: reflects types
- Document builder → OpenAPI model: builds document
- Type reflector → OpenAPI model: creates schemas
- Typed options → Security configuration: configures schemes
- Security configuration → OpenAPI model: sets security
- Webhook operations → Document builder: adds webhook operation
- Core router → Spec validator: validates document
- Core router → JSON YAML codec: serializes document
- Spec validator → OpenAPI model: checks invariants
- JSON YAML codec → Document consumer: returns JSON YAML
- Core router → UI option mapper: maps UI options
- Framework adapters → Adapter docs wiring: wires docs routes
- Adapter docs wiring → Docs UI handler: serves docs UI
- UI option mapper → Docs UI handler: configures handler
- Document consumer → OpenAPI model: uses typed models