spec

oaswrap/spec

Code-first, framework-agnostic OpenAPI 3.x spec builder for Go. Generate docs from route registrations and Go structs — no annotations, no vendor lock-in.

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.1.2, with full support for 3.0.x 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.
• InterceptSchema hook for type-level schema customization and override.
• InterceptProp hook for field-level property filtering and modification.
• RequiredPropByValidateTag option to derive required from validate struct tags.
• encoding.TextMarshaler/TextUnmarshaler types automatically reflected as type: string.
• EmbedReferencer interface and refer:"true" tag for embedded struct allOf $ref instead of field inlining.

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/irisopenapi
• 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, ServerName (3.2.0).

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.

Embedded struct references

By default, anonymous embedded struct fields are inlined into the parent schema. To emit an allOf $ref instead, use the refer:"true" tag or implement openapi.EmbedReferencer on the embedded type:

// Via struct tag
type Request struct {
    Base `refer:"true"`
    Name string `json:"name"`
}

// Via interface (useful when you own the embedded type)
type Base struct {
    ID int `json:"id"`
}

func (Base) ReferEmbedded() {}

Both produce:

Request:
  type: object
  properties:
    name:
      type: string
  allOf:
    - $ref: '#/components/schemas/Base'

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
		}),
		option.InterceptSchema(func(params openapi.InterceptSchemaParams) (stop bool, err error) {
			if params.Processed {
				params.Schema.Extensions = map[string]any{"x-go-type": params.Type.String()}
			}
			return false, nil
		}),
		option.InterceptProp(func(params openapi.InterceptPropParams) error {
			if params.Processed && params.Field.Tag.Get("internal") == "true" {
				return openapi.ErrSkipProperty
			}
			return nil
		}),
		option.RequiredPropByValidateTag(), // marks fields required when validate tag contains "required"
	),
)

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.
• Server name field.
• Response summary field.
• Tag parent and kind fields.
• Security scheme metadata and deprecation fields.
• components.mediaTypes.
• Media type and encoding fields: itemSchema, prefixEncoding, itemEncoding.
• Discriminator defaultMapping.
• 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

Acknowledgements

• swaggest/openapi-go and swaggest/jsonschema-go — parts of this library's reflection design are inspired by their work.