The three OASWrap libraries each solve one piece of the API documentation problem. Used together, they cover the full journey from spec generation to serving interactive docs — with no annotations, no third-party services, and no spec drift.

This post walks through a complete workflow: generate the spec with gswag during CI, embed it into your binary, and serve it with spec-ui.

Most Go projects treat API documentation as a separate task from testing. You write the handlers, write the tests, then — separately — write OpenAPI annotations or maintain a spec file by hand. The docs drift. The tests pass. Nobody notices until a consumer hits an undocumented edge case.

gswag takes a different approach: your OpenAPI spec is generated as a side-effect of running your Ginkgo integration tests. If the test passes, the spec reflects what your API actually does.

If you've maintained an OpenAPI spec by hand, you know the pain. The spec drifts from the code. A field gets renamed, a response changes, a new error code gets added — and the documentation doesn't follow. The solution most teams eventually reach is generating the spec from code, not maintaining it alongside it.

In the Go ecosystem, there are a few notable tools for this: swag (the annotation-based approach that many teams still use today), and a newer generation of code-first libraries — oaswrap/spec, Huma, and Fuego. They all solve the same problem, but with meaningfully different philosophies. This post walks through each one and helps you figure out which fits your situation.

spec-ui v0.2.0 is a significant release. It rethinks how UI providers are selected, makes offline deployments a first-class concern, and fixes a couple of bugs that could cause subtle, hard-to-debug issues in production.

Today we're shipping spec v0.4.0. This release focuses on expanding framework support with two new adapters, tightening up the generated spec output, and picking up the spec-ui v0.2.0 upgrade.