spec

oaswrap/spec

spec is a Go library for generating OpenAPI 3.0.x, 3.1.x, and 3.2.0 documents. It uses a router and functional options API, and owns its OpenAPI model and schema reflection — no external OpenAPI or JSON Schema generators needed. YAML serialization uses github.com/goccy/go-yaml.

Why oaswrap/spec?

• Native OpenAPI builder — paths, operations, components, validation, and schema reflection are all implemented in this repository without third-party OpenAPI dependencies.
• Framework-agnostic core — use spec.NewRouter for static generation, or drop in adapters for Chi, Echo, Gin, Fiber, net/http, and Mux.
• Code-first route documentation — register routes and their documentation together using Go functions and typed options.
• Version-aware output — defaults to OpenAPI 3.0.4, with full support for 3.1.2 and 3.2.0 features when selected.
• Direct model escape hatches — use typed openapi structs, Extensions for x-* fields, and Extra for official or future fields not yet wrapped by a helper option.
• Deterministic output — generated documents are stable enough for golden-file snapshot tests and CI documentation checks.

Features

• JSON and YAML generation.
• Framework-agnostic route registration with NewRouter, groups, route builders, and HTTP method helpers.
• Webhook registration helpers for OpenAPI 3.1.x and 3.2.0.
• OpenAPI 3.2.0 QUERY method and additional operation support.
• Request and response schema reflection from Go structs.
• Parameter reflection from path, query, header, cookie, and OpenAPI 3.2.0 querystring tags.
• JSON Schema/OpenAPI schema tags for examples, enums, constraints, nullability, read/write flags, content metadata, and XML metadata.
• Security helpers for API key, HTTP bearer/basic-style schemes, OAuth2, OpenID Connect, and mutual TLS.
• Duplicate response merging into oneOf.
• Low-level typed OpenAPI model for direct field control.
• spec.OneOf for explicit one-of schemas.
• SchemaExposer and StaticSchemaExposer hooks for custom reflected schemas.

Installation

Requirements:

• Go 1.22+

go get -u github.com/oaswrap/spec

Quick Start

package main

import (
	"log"

	"github.com/oaswrap/spec"
	"github.com/oaswrap/spec/openapi"
	"github.com/oaswrap/spec/option"
)

func main() {
	r := spec.NewRouter(
		option.WithOpenAPIVersion(openapi.Version320),
		option.WithTitle("Users API"),
		option.WithVersion("1.0.0"),
		option.WithServer("https://api.example.com"),
		option.WithSecurity("bearerAuth", option.SecurityHTTPBearer("bearer")),
	)

	v1 := r.Group("/api/v1", option.GroupTags("users"))
	v1.Post("/login",
		option.Summary("Login"),
		option.Request(new(LoginRequest)),
		option.Response(200, new(LoginResponse)),
	)
	v1.Get("/users/{id}",
		option.Summary("Get user"),
		option.Request(new(GetUserRequest)),
		option.Response(200, new(User)),
	)

	if err := r.WriteSchemaTo("openapi.yaml"); err != nil {
		log.Fatal(err)
	}
}

type LoginRequest struct {
	Username string `json:"username" required:"true"`
	Password string `json:"password" required:"true" writeOnly:"true"`
}

type LoginResponse struct {
	Token string `json:"token" required:"true"`
}

type GetUserRequest struct {
	ID string `path:"id" required:"true" description:"User identifier"`
}

type User struct {
	ID   string `json:"id" required:"true"`
	Name string `json:"name"`
}

Output

spec.NewRouter and spec.NewGenerator expose the following output methods:

Framework Adapters

Use the core spec package for static generation and CI workflows. Use an adapter when you want route registration, spec generation, and docs UI wiring in a single framework-specific router.

Adapter module import paths:

• github.com/oaswrap/spec/adapter/chiopenapi
• github.com/oaswrap/spec/adapter/echoopenapi
• github.com/oaswrap/spec/adapter/echov5openapi
• github.com/oaswrap/spec/adapter/fiberopenapi
• github.com/oaswrap/spec/adapter/fiberv3openapi
• github.com/oaswrap/spec/adapter/ginopenapi
• github.com/oaswrap/spec/adapter/httpopenapi
• github.com/oaswrap/spec/adapter/muxopenapi

OpenAPI Options

Root options are passed to spec.NewRouter or spec.NewGenerator.

r := spec.NewRouter(
	option.WithOpenAPIVersion(openapi.Version312),
	option.WithTitle("Payments API"),
	option.WithInfoSummary("Payments API"),
	option.WithVersion("1.4.0"),
	option.WithDescription("Payment operations."),
	option.WithTermsOfService("https://example.com/terms"),
	option.WithContact(openapi.Contact{Name: "API Team", Email: "api@example.com"}),
	option.WithLicense(openapi.License{Name: "Apache 2.0", URL: "https://www.apache.org/licenses/LICENSE-2.0.html"}),
	option.WithExternalDocs("https://docs.example.com", "Full documentation"),
	option.WithServer("https://api.example.com", option.ServerDescription("Production")),
	option.WithTag("payments", option.TagDescription("Payment operations")),
	option.WithStripTrailingSlash(),
)

Adapter-only options: WithDisableDocs, WithDocsPath, WithSpecPath, WithCacheAge, WithUIOption, WithSwaggerUI, WithStoplightElements, WithReDoc, WithScalar, and WithRapiDoc affect adapter docs/spec endpoints, not core static generation output.

Tag options: TagSummary, TagDescription, TagExternalDocs, TagParent (3.2.0), TagKind (3.2.0).

Server options: ServerDescription, ServerVariables.

Routes and Groups

api := r.Group("/api/v1", option.GroupTags("v1"))

api.Get("/users/{id}",
	option.OperationID("getUser"),
	option.Summary("Get user"),
	option.Description("Returns one user."),
	option.Tags("users"),
	option.Security("bearerAuth"),
	option.Request(new(GetUserRequest)),
	option.Response(200, new(User), option.ContentDescription("OK")),
	option.Response(404, nil, option.ContentDescription("Not Found")),
)

Router methods:

Get, Post, Put, Delete, Patch, Options, Head, Trace, Query (3.2.0), Add, Webhook (3.1.x+), AddWebhook (3.1.x+), NewRoute(...).Method(...).Path(...).With(...), Group, Route, With.

Group options:

Operation options:

Content options:

Example options: ExampleSummary, ExampleDescription, ExampleExternalValue, ExampleDataValue (3.2.0), ExampleSerializedValue (3.2.0).

Security

r := spec.NewRouter(
	option.WithSecurity("apiKey", option.SecurityAPIKey("X-API-Key", openapi.SecuritySchemeAPIKeyInHeader)),
	option.WithSecurity("bearerAuth", option.SecurityHTTPBearer("bearer")),
	option.WithSecurity("mtls", option.SecurityMutualTLS()),
	option.WithSecurity("oauth2", option.SecurityOAuth2AuthorizationCode(
		"https://auth.example.com/oauth/authorize",
		"https://auth.example.com/oauth/token",
		map[string]string{
			"read":  "Read access",
			"write": "Write access",
		},
	)),
	option.WithSecurity("oidc", option.SecurityOpenIDConnect("https://auth.example.com/.well-known/openid-configuration")),
)

Security helpers:

• SecurityAPIKey(name, in)
• SecurityHTTPBearer(scheme, bearerFormat...)
• SecurityOAuth2(flows)
• SecurityOAuth2Implicit(authorizationURL, scopes, flowOpts...)
• SecurityOAuth2Password(tokenURL, scopes, flowOpts...)
• SecurityOAuth2ClientCredentials(tokenURL, scopes, flowOpts...)
• SecurityOAuth2AuthorizationCode(authorizationURL, tokenURL, scopes, flowOpts...)
• SecurityOAuth2DeviceAuthorization(deviceAuthorizationURL, tokenURL, scopes, flowOpts...) — OpenAPI 3.2.0
• OAuthRefreshURL(url)
• SecurityOpenIDConnect(url)
• SecurityMutualTLS()
• SecurityDescription(description)
• SecurityOAuth2MetadataURL(url) — OpenAPI 3.2.0
• SecurityDeprecated(deprecated...) — OpenAPI 3.2.0

Reflection Tags

Request structs are split into parameters and request body:

• Fields with path, query, header, cookie, or querystring tags become OpenAPI parameters.
• querystring is only valid for OpenAPI 3.2.0.
• Body fields use json names by default; for application/x-www-form-urlencoded and multipart/form-data they use form names, falling back to json.
• json:"-" skips a field.
• Path parameters are always marked required.
• Adapter packages can add framework-specific parameter tags with ParameterTagMapping (e.g. Gin uses uri, Fiber uses params, Echo uses param).

type SearchRequest struct {
	ID       string `path:"id" required:"true" description:"Resource ID"`
	Status   string `query:"status" enum:"active,inactive"`
	TraceID  string `header:"X-Trace-ID"`
	Session  string `cookie:"session"`
	Name     string `json:"name" minLength:"2" maxLength:"80"`
	File     []byte `form:"file" format:"binary" description:"Upload file"`
	Internal string `json:"-"`
}

Naming and location tags:

Schema tags:

Reflection intentionally omits keywords that are invalid for the selected OpenAPI version. For example, const, examples, contentEncoding, and contentMediaType are not emitted for OpenAPI 3.0.x.

Reflected Go Types

Custom types can expose their own schema when tags are not expressive enough:

type Slug string

func (*Slug) OpenAPISchema(version string) *openapi.Schema {
	if version == openapi.Version304 {
		return &openapi.Schema{Type: "string", Format: "slug"}
	}
	return &openapi.Schema{Type: []string{"string", "null"}, Format: "slug"}
}

For static schemas, implement OpenAPISchema() *openapi.Schema instead. Field tags are still applied on top of custom schemas.

Reflector Configuration

r := spec.NewRouter(
	option.WithReflectorConfig(
		option.InlineRefs(),
		option.StripDefNamePrefix("DTO"),
		option.TypeMapping(NullString{}, new(string)),
		option.ParameterTagMapping(openapi.ParameterInPath, "params"),
		option.InterceptDefName(func(t reflect.Type, defaultName string) string {
			return defaultName
		}),
	),
)

OpenAPI 3.2

Selecting openapi.Version320 enables the following additional features:

• Router.Query(path, opts...) — new QUERY HTTP method.
• Custom HTTP methods via Add, emitted as additionalOperations.
• querystring parameter tags.
• Root $self field.
• Tag parent and kind fields.
• Security scheme metadata and deprecation fields.
• components.mediaTypes.
• Media type and encoding fields: itemSchema, prefixEncoding, itemEncoding.
• Example dataValue and serializedValue fields.
• XML nodeType.

Low-Level OpenAPI Control

The openapi package exposes typed low-level OpenAPI structs. Use them when a feature does not require reflection or doesn't yet have a convenience option.

r := spec.NewRouter(
	option.WithOpenAPIVersion(openapi.Version320),
	option.WithTitle("API"),
	option.WithVersion("1.0.0"),
	option.WithDocument(func(doc *openapi.Document) {
		doc.Webhooks = map[string]*openapi.PathItem{
			"user.created": {
				Post: &openapi.Operation{
					Responses: map[string]*openapi.Response{
						"202": {Description: "Accepted"},
					},
				},
			},
		}
		doc.Extensions = map[string]any{"x-company": "oaswrap"}
		doc.Extra = map[string]any{"futureOfficialField": true}
	}),
)

• Use Extensions for x-* specification extensions.
• Use Extra to emit official or future fields not yet typed.
• Use CustomizeOperation to mutate an operation directly.
• Use WithDocument to mutate the final document before output.

The library validates many OpenAPI invariants but does not attempt exhaustive semantic validation for every rule in the specification.

Examples

Complete working examples are in the examples/ directory:

• Basic — standalone spec generation.
• Petstore — full Petstore API with routes and models.
• Adapter examples — framework-specific examples in adapter/*/example.

API Reference

Full documentation is available at pkg.go.dev/github.com/oaswrap/spec.

Contributing

Issues and pull requests are welcome. Please check existing issues and discussions before starting work on new features.

License

MIT