kin-openapi

kin-openapi is a Go library for handling OpenAPI specification files. It supports Swagger 2.0 (as openapi2) alongside OpenAPI 3.0, 3.1, and partial 3.2 (as openapi3), covering the full lifecycle of loading a spec, validating it against the OpenAPI schema rules, converting between Swagger 2.0 and OpenAPI 3.0, and using the parsed document to validate real HTTP requests and responses at runtime.

The package is organized into focused submodules: openapi2 and openapi2conv for legacy Swagger files and their conversion to OpenAPI 3, openapi3 for the core document model and validation, openapi3filter for validating live HTTP traffic against a loaded spec (with a gorilla/mux-based router for matching requests to operations), and openapi3gen for generating openapi3.Schema values directly from Go types via reflection.

Because it is widely embedded as a dependency rather than run standalone, kin-openapi underpins a number of other well-known Go OpenAPI tools, including oapi-codegen (client/server code generation), oasdiff (spec diffing), fuego (spec generation from source), and apisprout (mock servers) — making it a de facto standard building block for OpenAPI tooling in the Go ecosystem.

What You Get

• A Loader that resolves $ref references across local and (optionally) external files and can parse from a file, byte slice, URL, or stdin
• Full validation of OpenAPI 3.0/3.1/3.2 documents, with stable kebab-case error codes (e.g. operation-responses-required) exposed via ValidationErrorCodes() for machine-readable diagnostics
• openapi2conv for converting legacy Swagger 2.0 documents into OpenAPI 3.0
• openapi3filter for validating actual HTTP requests and responses against the loaded spec, plus a gorilla/mux-backed router that maps an incoming *http.Request to the matching OpenAPI operation
• openapi3gen for generating *openapi3.Schema values directly from Go struct types via reflection, useful for spec generation tooling
• Optional Origin tracking that records the file, line, and column of every element in the source document, useful for linters, diff tools, and editors that need precise error locations

Common Use Cases

• Validating an OpenAPI/Swagger spec file in CI before publishing it, via the bundled cmd/validate command
• Building API gateways or middleware that validate incoming requests and outgoing responses against a contract at runtime
• Writing code-generation tools (client SDKs, server stubs, mock servers) that need a reliable in-memory model of an OpenAPI document
• Converting an older Swagger 2.0 API definition to OpenAPI 3.0 as part of a migration
• Building linters or spec-diffing tools that need precise source locations for validation errors, using the Origin tracking feature

Under The Hood

Architecture

The library is organized as a set of focused, loosely-coupled packages rather than one monolith: openapi2 and openapi3 hold the document models and (de)serialization logic for their respective spec versions, openapi2conv bridges the two, openapi3filter layers HTTP request/response validation and operation routing on top of a loaded openapi3.T, and openapi3gen generates schemas from Go types independently of the loader. The Loader type in openapi3/loader.go is the central entry point, responsible for resolving $ref pointers (local and, when enabled, external) into a fully-dereferenced in-memory document graph that the rest of the packages operate on; downstream consumers like openapi3filter’s router and validators depend on this resolved graph rather than re-parsing anything themselves, so changing the loader’s resolution semantics would ripple through every other package.

Tech Stack

Written in Go (module targets Go 1.25), with a deliberately small dependency footprint: github.com/oasdiff/yaml and github.com/oasdiff/yaml3 for YAML decoding, github.com/santhosh-tekuri/jsonschema/v6 for JSON Schema validation, github.com/go-openapi/jsonpointer for $ref pointer resolution, github.com/gorilla/mux for the HTTP router used by openapi3filter, and github.com/stretchr/testify for assertions in the test suite. No web framework or database dependency — it is a pure library meant to be embedded.

Code Quality

The test suite is extensive: roughly two-thirds of the repository’s Go files (203 of 297) are _test.go files, including many named after specific GitHub issues (issue1044_test.go, issue230_test.go, etc.), indicating a strong regression-test discipline where reported bugs get a permanent named test. CI (.github/workflows/go.yml) runs the suite across Linux, macOS, and Windows on each push and pull request, and also caches a large external fixture set (the APIs.guru OpenAPI directory) for cross-validation against real-world specs. Validation errors are typed and carry stable kebab-case codes via a CodedError interface rather than relying on string matching, and a MultiError mode exists for aggregating validation failures instead of stopping at the first one.

What Makes It Unique

Unlike most OpenAPI libraries that only validate a spec file itself, kin-openapi extends validation into runtime HTTP traffic via openapi3filter, pairing spec validation with a request router so a service can reject requests that don’t conform to its own contract. Its Origin tracking feature — recording exact file/line/column provenance for every parsed element, independent of the OpenAPI spec’s own data model — is comprehensive tooling support that most comparable libraries (like libopenapi) don’t expose in the same depth, and its adoption as a dependency by several other prominent Go OpenAPI tools (oapi-codegen, oasdiff, fuego) reflects its role as foundational infrastructure rather than an end-user tool.