Skip to main content

From Tests to Docs: A Complete OASWrap Workflow

· 4 min read
Ahmad Faiz Kamaludin
Oaswrap Maintainer

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.

Test-Driven API Documentation with gswag and Ginkgo

· 4 min read
Ahmad Faiz Kamaludin
Oaswrap Maintainer

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.

Code-First OpenAPI in Go: Comparing spec, Huma, Fuego, and swag

· 8 min read
Ahmad Faiz Kamaludin
Oaswrap Maintainer

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.