Skip to main content

Introduction

OASWrap is a collection of Go libraries for building and serving OpenAPI 3.x documentation without vendor lock-in.

Libraries​

spec​

A lightweight, framework-agnostic OpenAPI 3.x specification builder. Write your API documentation in pure Go code with full type safety — no annotations, no code comments required.

go get github.com/oaswrap/spec
  • Build specs programmatically in Go
  • Works standalone or with any web framework
  • Adapter ecosystem for Chi, Echo, Gin, Fiber, net/http, and more
  • CI/CD ready for build-time spec generation

gswag​

Generate OpenAPI 3.0 specs as a side-effect of running Ginkgo v2 integration tests. Inspired by rswag — define API docs alongside real, executable tests using a nested DSL.

go get github.com/oaswrap/gswag
  • Spec emerges from real HTTP requests, not annotations
  • Captures live request/response examples automatically
  • Parallel Ginkgo suite support (ginkgo -p)
  • Built-in structural and JSON Schema validation

spec-ui​

Serve beautiful, interactive API documentation with multiple UI providers as standard Go HTTP handlers.

go get github.com/oaswrap/spec-ui
  • 5 UI providers: Swagger UI, Stoplight Elements, ReDoc, Scalar, RapiDoc
  • Works with any Go HTTP router
  • CDN mode (lightweight) or embedded mode (air-gapped deployments)
  • Switch providers by changing a single import

How They Work Together​

spec generates your OpenAPI specification at build time. gswag generates it as a side-effect of your Ginkgo tests. spec-ui serves either output as interactive documentation. You can use them independently or together:

// Generate the spec
r := spec.NewRouter(
    option.WithTitle("My API"),
    option.WithVersion("1.0.0"),
)
r.Get("/users", option.Summary("List users"), option.Response(200, new([]User)))
r.WriteSchemaTo("openapi.yaml")

// Serve the spec as interactive docs
handler := specui.NewHandler(
    specui.WithSpecFile("openapi.yaml"),
    swaggerui.WithUI(),
)

Framework adapters (chiopenapi, ginopenapi, etc.) combine both — automatically generating the spec from your routes and serving the documentation UI.