Introduction

oaswrap/spec is a code-first, framework-agnostic OpenAPI 3.x specification builder for Go that gives you full control over API documentation without annotations.

Why oaswrap/spec?

• Native OpenAPI Builder — Paths, operations, components, validation, and reflection are implemented in oaswrap/spec
• Framework Agnostic — Works standalone for static generation or with adapters for common Go frameworks
• Version-Aware Output — Defaults to OpenAPI 3.1.2, with support for 3.0.x and 3.2.0
• Programmatic Control — Build specs in pure Go code with full type safety
• Adapter Ecosystem — Seamless integration with popular frameworks via dedicated adapters
• CI/CD Ready — Generate specs at build time for documentation pipelines

When to Use

Use spec for static generation when you:

• Generate OpenAPI files at build time
• Integrate with CI/CD pipelines
• Build custom documentation tools
• Need static spec generation from existing code

Use framework adapters when you:

• Want automatic spec generation from routes
• Need zero-configuration setup
• Prefer inline OpenAPI configuration alongside route definitions
• Want route registration + documentation in one step

Comparison

	oaswrap/spec	swag/swaggo	Huma
Style	Code-first	Annotation-based	Framework + validation
Type Safety	Full	Limited	Full
Framework	Any / Agnostic	Any	Built-in
Standalone	Yes	Yes	No
Validation	Spec only	Spec only	Request/Response

vs swag/swaggo: oaswrap uses pure Go code for type safety and better IDE support. swag uses code comments and annotations.

vs Huma: Huma is a complete HTTP framework with built-in OpenAPI generation, validation, and middleware. oaswrap/spec is a lightweight documentation builder — use it if you have existing code, prefer framework flexibility, or need standalone spec generation.

Status

The library is in active development. While core functionality is solid, consider it beta software. Thorough testing is recommended before production use.