Introduction

A Go project for handling OpenAPI files. We target:

• OpenAPI v2.0 (formerly known as Swagger)
• OpenAPI v3.0
• OpenAPI v3.1
• OpenAPI v3.2 Partially: Media Type Object itemSchema, Path Item Object query (the HTTP QUERY method) and additionalOperations (custom HTTP methods).

Licensed under the MIT License.

Contributors, users and sponsors

The project has received pull requests from many people. Thanks to everyone!

Please, give back to this project by becoming a sponsor.

Here's some projects that depend on kin-openapi:

• github.com/go-fuego/fuego - "Framework generating OpenAPI 3 spec from source code"
• github.com/a-h/rest - "Generate OpenAPI 3.0 specifications from Go code without annotations or magic comments"
• github.com/Tufin/oasdiff - "A diff tool for OpenAPI Specification 3"
• github.com/danielgtaylor/apisprout - "Lightweight, blazing fast, cross-platform OpenAPI 3 mock server with validation"
• github.com/oapi-codegen/oapi-codegen - "Generate Go client and server boilerplate from OpenAPI 3 specifications"
• github.com/dunglas/vulcain - "Use HTTP/2 Server Push to create fast and idiomatic client-driven REST APIs"
• github.com/danielgtaylor/restish - "...a CLI for interacting with REST-ish HTTP APIs with some nice features built-in"
• github.com/goadesign/goa - "Design-based APIs and microservices in Go"
• github.com/hashicorp/nomad-openapi - "Nomad is an easy-to-use, flexible, and performant workload orchestrator that can deploy a mix of microservice, batch, containerized, and non-containerized applications. Nomad is easy to operate and scale and has native Consul and Vault integrations."
• gitlab.com/jamietanna/httptest-openapi (blog post) - "Go OpenAPI Contract Verification for use with net/http"
• github.com/SIMITGROUP/openapigenerator - "Openapi v3 microservices generator"
• https://github.com/projectsveltos/addon-controller - "Kubernetes add-on controller designed to manage tens of clusters."
• (Feel free to add your project by creating an issue or a pull request)

Alternatives

• libopenapi a fully featured, high performance OpenAPI 3.1, 3.0 and Swagger parser, library, validator and toolkit
• go-swagger stated OpenAPIv3 won't be supported
• swaggo has an open issue on OpenAPIv3

Be sure to check OpenAPI Initiative's great tooling list as well as OpenAPI.Tools.

Structure

• openapi2 (Go Reference)
  • Support for OpenAPI 2 files, including serialization, deserialization, and validation.
• openapi2conv (Go Reference)
  • Converts OpenAPI 2 files into OpenAPI 3 files.
• openapi3 (Go Reference)
  • Support for OpenAPI 3 files, including serialization, deserialization, and validation.
• openapi3filter (Go Reference)
  • Validates HTTP requests and responses
  • Provides a gorilla/mux router for OpenAPI operations
• openapi3gen (Go Reference)
  • Generates *openapi3.Schema values for Go types.

Some recipes

Validating an OpenAPI document

go run github.com/getkin/kin-openapi/cmd/validate@latest [--defaults] [--examples] [--ext] [--patterns] -- <local YAML or JSON file>

Loading OpenAPI document

Use openapi3.Loader, which resolves all references:

loader := openapi3.NewLoader()
doc, err := loader.LoadFromFile("my-openapi-spec.json")

Tracking source locations (Origin)

When IncludeOrigin is enabled, the loader records the file, line, and column of each element in the OpenAPI document. This is useful for tools that need to report errors or changes with precise source locations (e.g. linters, diff tools, editors).

loader := openapi3.NewLoader()
loader.IncludeOrigin = true
doc, err := loader.LoadFromFile("my-openapi-spec.json")

// Each element has an Origin field with source location info
fmt.Println(doc.Info.Origin.Key.File)   // "my-openapi-spec.json"
fmt.Println(doc.Info.Origin.Key.Line)   // 2
fmt.Println(doc.Info.Origin.Key.Column) // 1

The Origin struct contains three parts:

• Key — the location of the object itself (file, line, column).
• Fields — locations of scalar fields within the object (e.g. origin.Fields["description"] gives the line of the description field).
• Sequences — locations of items in sequence-valued fields. For example, origin.Sequences["enum"] gives the location of each item in an enum array. This is used for fields like enum, required, and servers where the individual items are scalars and don't have their own Origin field.

Origin data is populated by an internal post-processing step after YAML decoding — it is not part of the OpenAPI spec itself. For this reason, Origin fields are excluded from serialization. If you marshal a loaded document back to JSON/YAML, origin data will not appear in the output.

Identifying validation errors by code

Each validation error carries a stable, kebab-case code (e.g. operation-responses-required), independent of the message text, so tools can suppress specific findings, assign per-rule severities, or emit machine-readable diagnostics. The full catalog is available from openapi3.ValidationErrorCodes().

err := doc.Validate(ctx, openapi3.EnableMultiError())
for _, e := range err.(openapi3.MultiError) {
	var coded openapi3.CodedError
	if errors.As(e, &coded) {
		fmt.Println(coded.Code(), e) // e.g. "operation-responses-required value of responses must be an object"
	}
}

Getting OpenAPI operation that matches request

loader := openapi3.NewLoader()
doc, _ := loader.LoadFromData([]byte(`...`))
_ = doc.Validate(loader.Context)
router, _ := gorillamux.NewRouter(doc)
route, pathParams, _ := router.FindRoute(httpRequest)
// Do something with route.Operation

Validating HTTP requests/responses

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/getkin/kin-openapi/openapi3"
	"github.com/getkin/kin-openapi/openapi3filter"
	"github.com/getkin/kin-openapi/routers/gorillamux"
)

func main() {
	ctx := context.Background()
	loader := &openapi3.Loader{Context: ctx, IsExternalRefsAllowed: true}
	doc, _ := loader.LoadFromFile(".../My-OpenAPIv3-API.yml")
	// Validate document
	_ = doc.Validate(ctx)
	router, _ := gorillamux.NewRouter(doc)
	httpReq, _ := http.NewRequest(http.MethodGet, "/items", nil)

	// Find route
	route, pathParams, _ := router.FindRoute(httpReq)

	// Validate request
	requestValidationInput := &openapi3filter.RequestValidationInput{
		Request:    httpReq,
		PathParams: pathParams,
		Route:      route,
	}
	_ = openapi3filter.ValidateRequest(ctx, requestValidationInput)

	// Handle that request
	// --> YOUR CODE GOES HERE <--
	responseHeaders := http.Header{"Content-Type": []string{"application/json"}}
	responseCode := 200
	responseBody := []byte(`{}`)

	// Validate response
	responseValidationInput := &openapi3filter.ResponseValidationInput{
		RequestValidationInput: requestValidationInput,
		Status:                 responseCode,
		Header:                 responseHeaders,
	}
	responseValidationInput.SetBodyBytes(responseBody)
	_ = openapi3filter.ValidateResponse(ctx, responseValidationInput)
}

Custom content type for body of HTTP request/response

By default, the library parses a body of the HTTP request and response of a few content types e.g. "text/plain" or "application/json". To support other content types you must register decoders for them:

func main() {
	// ...

	// Register a body's decoder for content type "application/xml".
	openapi3filter.RegisterBodyDecoder("application/xml", xmlBodyDecoder)

	// Now you can validate HTTP request that contains a body with content type "application/xml".
	requestValidationInput := &openapi3filter.RequestValidationInput{
		Request:    httpReq,
		PathParams: pathParams,
		Route:      route,
	}
	if err := openapi3filter.ValidateRequest(ctx, requestValidationInput); err != nil {
		panic(err)
	}

	// ...

	// And you can validate HTTP response that contains a body with content type "application/xml".
	if err := openapi3filter.ValidateResponse(ctx, responseValidationInput); err != nil {
		panic(err)
	}
}

func xmlBodyDecoder(body io.Reader, h http.Header, schema *openapi3.SchemaRef, encFn openapi3filter.EncodingFn) (decoded any, err error) {
	// Decode body to a primitive, []any, or map[string]any.
}

Custom function to check uniqueness of array items

By default, the library checks unique items using the following predefined function:

func isSliceOfUniqueItems(xs []any) bool {
	s := len(xs)
	m := make(map[string]struct{}, s)
	for _, x := range xs {
		key, _ := json.Marshal(&x)
		m[string(key)] = struct{}{}
	}
	return s == len(m)
}

In the predefined function json.Marshal is used to generate a string that can be used as a map key which is to check the uniqueness of an array when the array items are objects or arrays. You can register you own function according to your input data to get better performance:

func main() {
	// ...

	// Register a customized function used to check uniqueness of array.
	openapi3.RegisterArrayUniqueItemsChecker(arrayUniqueItemsChecker)

	// ... other validate codes
}

func arrayUniqueItemsChecker(items []any) bool {
	// Check the uniqueness of the input slice
}

Custom function to change schema error messages

By default, the error message returned when validating a value includes the error reason, the schema, and the input value.

For example, given the following schema:

{
  "type": "string",
  "allOf": [
    { "pattern": "[A-Z]" },
    { "pattern": "[a-z]" },
    { "pattern": "[0-9]" },
    { "pattern": "[!@#$%^&*()_+=-?~]" }
  ]
}

Passing the input value "secret" to this schema will produce the following error message:

string doesn't match the regular expression "[A-Z]"
Schema:
  {
    "pattern": "[A-Z]"
  }

Value:
  "secret"

Including the original value in the error message can be helpful for debugging, but it may not be appropriate for sensitive information such as secrets.

To disable the extra details in the schema error message, you can set the openapi3.SchemaErrorDetailsDisabled option to true:

func main() {
	// ...

	// Disable schema error detailed error messages
	openapi3.SchemaErrorDetailsDisabled = true

	// ... other validate codes
}

This will shorten the error message to present only the reason:

string doesn't match the regular expression "[A-Z]"

For more fine-grained control over the error message, you can pass a custom openapi3filter.Options object to openapi3filter.RequestValidationInput that includes a openapi3filter.CustomSchemaErrorFunc.

func validationOptions() *openapi3filter.Options {
	options := &openapi3filter.Options{}
	options.WithCustomSchemaErrorFunc(safeErrorMessage)
	return options
}

func safeErrorMessage(err *openapi3.SchemaError) string {
	return err.Reason
}

This will change the schema validation errors to return only the Reason field, which is guaranteed to not include the original value.

Reconciling component $ref types

ReferencesComponentInRootDocument is a useful helper function to check if a component reference coincides with a reference in the root document's component objects fixed fields.

This can be used to determine if two schema definitions are of the same structure, helpful for code generation tools when generating go type models.

doc, err = loader.LoadFromFile("openapi.yml")

for _, path := range doc.Paths.InMatchingOrder() {
	pathItem := doc.Paths.Find(path)

	if pathItem.Get == nil || pathItem.Get.Responses.Status(200) {
		continue
	}

	for _, s := range pathItem.Get.Responses.Status(200).Value.Content {
		name, match := ReferencesComponentInRootDocument(doc, s.Schema)
		fmt.Println(path, match, name) // /record true #/components/schemas/BookRecord
	}
}

CHANGELOG: Sub-v1 breaking API changes

v0.147.0

• (*openapi3.PathItem).SetOperation(string, *Operation) no longer panics on unhandled HTTP methods: these are now stored in the new openapi3.PathItem.AdditionalOperations field (passing a nil operation deletes the entry).
• (*openapi3.PathItem).GetOperation(string) and (*openapi3.PathItem).Operations() now also report the new openapi3.PathItem.Query field (the OpenAPI 3.2 HTTP QUERY method) and the openapi3.PathItem.AdditionalOperations entries. Routers and validators consequently match these methods.
• openapi2conv.FromV3(..) and openapi2conv.FromV3PathItem(..) now return an error for operations whose HTTP method Swagger 2.0 cannot express (QUERY, TRACE, CONNECT and custom methods) instead of panic-ing.

v0.145.0

• (*openapi3.PathItem).GetOperation(string) now returns nil on unhandled HTTP methods instead of panic-ing.
• (*openapi2.PathItem).GetOperation(string) now returns nil on unhandled HTTP methods instead of panic-ing.

v0.144.0

• openapi3filter.ValidationHandler.AuthenticationFunc no longer defaults to NoopAuthenticationFunc. Users now have to explicitly set the field and implement their own AuthenticationFunc or use the noop impl should they wish to.

v0.143.0

• Removed the openapi3.StringMap[V] type (an internal helper for origin-aware map unmarshalling, obsolete since origin tracking moved to a separate OriginTree pass). openapi3.Discriminator.Mapping field type changed from StringMap[MappingRef] to map[string]MappingRef, and openapi3.OAuthFlow.Scopes from StringMap[string] to map[string]string.

v0.137.0

• Reinstated openapi3.*Ptr(..) funcs for Go 1.25

v0.136.0

• openapi3.Schema.ExclusiveMin and openapi3.Schema.ExclusiveMax fields changed from bool to ExclusiveBound (a union type holding *bool for OpenAPI 3.0 or *float64 for OpenAPI 3.1).
• openapi3.Schema.PrefixItems field changed from []*SchemaRef to SchemaRefs.
• openapi3.Schema.UnevaluatedItems and openapi3.Schema.UnevaluatedProperties fields changed from *SchemaRef to BoolSchema (a union type accepting either a boolean or a schema object).
• Removed openapi3.*Ptr(..) funcs: they all can be replaced with new(..) since Go 1.26

v0.135.0

• openapi3.MediaType.Encoding field type changed from map[string]*Encoding to Encodings
• openapi3.Server.Variables field type changed from map[string]*ServerVariable to ServerVariables

v0.134.0

• openapi3.Location gained File and Name fields (string type, replacing previous int-only struct layout)
• openapi3.Origin gained Sequences field (map[string][]Location, extending previous map[string]Location-only struct)

v0.131.0

• No longer openapi3filter.RegisterBodyDecoder the openapi3filter.ZipFileBodyDecoder by default.

v0.129.0

• openapi3.Discriminator.Mapping and openapi3.OAuthFlow.Scopes fields went from a map[string]string to the new type StringMap

v0.127.0

• Downgraded github.com/gorilla/mux dep from 1.8.1 to 1.8.0.

v0.126.0

• openapi3.CircularReferenceError and openapi3.CircularReferenceCounter are removed. openapi3.Loader now implements reference backtracking, so any kind of circular references should be properly resolved.
• InternalizeRefs now takes a refNameResolver that has access to openapi3.T and more properties of the reference needing resolving.
• The DefaultRefNameResolver has been updated, choosing names that will be less likely to collide with each other. Because of this internalized specs will likely change slightly.
• openapi3.Format and openapi3.FormatCallback are removed and the type of openapi3.SchemaStringFormats has changed.

v0.125.0

• The openapi3filter.ErrFunc and openapi3filter.LogFunc func types now take the validated request's context as first argument.

v0.124.0

• openapi3.Schema.Type & openapi2.Parameter.Type fields went from a string to the type *Type with methods: Includes, Is, Permits & Slice.

v0.122.0

• Paths field of openapi3.T is now a pointer
• Responses field of openapi3.Operation is now a pointer
• openapi3.Paths went from map[string]*PathItem to a struct with an Extensions field and methods: Set, Value, Len, Map, and New*.
• openapi3.Callback went from map[string]*PathItem to a struct with an Extensions field and methods: Set, Value, Len, Map, and New*.
• openapi3.Responses went from map[string]*ResponseRef to a struct with an Extensions field and methods: Set, Value, Len, Map, and New*.
• (openapi3.Responses).Get(int) renamed to (*openapi3.Responses).Status(int)

v0.121.0

• Introduce openapi3.RequestBodies (an alias on map[string]*openapi3.ResponseRef) and use it in place of openapi3.Responses for field openapi3.Components.Responses.

v0.116.0

• Dropped openapi3filter.DefaultOptions. Use &openapi3filter.Options{} directly instead.

v0.113.0

• The string format email has been removed by default. To use it please call openapi3.DefineStringFormat("email", openapi3.FormatOfStringForEmail).
• Field openapi3.T.Components is now a pointer.
• Fields openapi3.Schema.AdditionalProperties and openapi3.Schema.AdditionalPropertiesAllowed are replaced by openapi3.Schema.AdditionalProperties.Schema and openapi3.Schema.AdditionalProperties.Has respectively.
• Type openapi3.ExtensionProps is now just map[string]any and extensions are accessible through the Extensions field.

v0.112.0

• (openapi3.ValidationOptions).ExamplesValidationDisabled has been unexported.
• (openapi3.ValidationOptions).SchemaFormatValidationEnabled has been unexported.
• (openapi3.ValidationOptions).SchemaPatternValidationDisabled has been unexported.

v0.111.0

• Changed func (*_) Validate(ctx context.Context) error to func (*_) Validate(ctx context.Context, opts ...ValidationOption) error.
• openapi3.WithValidationOptions(ctx context.Context, opts *ValidationOptions) context.Context prototype changed to openapi3.WithValidationOptions(ctx context.Context, opts ...ValidationOption) context.Context.

v0.101.0

• openapi3.SchemaFormatValidationDisabled has been removed in favour of an option openapi3.EnableSchemaFormatValidation() passed to openapi3.T.Validate. The default behaviour is also now to not validate formats, as the OpenAPI spec mentions the format is an open value.

v0.84.0

• The prototype of openapi3gen.NewSchemaRefForValue changed:
  • It no longer returns a map but that is still accessible under the field (*Generator).SchemaRefs.
  • It now takes in an additional argument (basically doc.Components.Schemas) which gets written to so $ref cycles can be properly handled.

v0.61.0

• Renamed openapi2.Swagger to openapi2.T.
• Renamed openapi2conv.FromV3Swagger to openapi2conv.FromV3.
• Renamed openapi2conv.ToV3Swagger to openapi2conv.ToV3.
• Renamed openapi3.LoadSwaggerFromData to openapi3.LoadFromData.
• Renamed openapi3.LoadSwaggerFromDataWithPath to openapi3.LoadFromDataWithPath.
• Renamed openapi3.LoadSwaggerFromFile to openapi3.LoadFromFile.
• Renamed openapi3.LoadSwaggerFromURI to openapi3.LoadFromURI.
• Renamed openapi3.NewSwaggerLoader to openapi3.NewLoader.
• Renamed openapi3.Swagger to openapi3.T.
• Renamed openapi3.SwaggerLoader to openapi3.Loader.
• Renamed openapi3filter.ValidationHandler.SwaggerFile to openapi3filter.ValidationHandler.File.
• Renamed routers.Route.Swagger to routers.Route.Spec.

v0.51.0

• Type openapi3filter.Route moved to routers (and Route.Handler was dropped. See https://github.com/getkin/kin-openapi/issues/329)
• Type openapi3filter.RouteError moved to routers (so did ErrPathNotFound and ErrMethodNotAllowed which are now RouteErrors)
• Routers' FindRoute(...) method now takes only one argument: *http.Request
• getkin/kin-openapi/openapi3filter.Router moved to getkin/kin-openapi/routers/legacy
• openapi3filter.NewRouter() and its related WithSwaggerFromFile(string), WithSwagger(*openapi3.Swagger), AddSwaggerFromFile(string) and AddSwagger(*openapi3.Swagger) are all replaced with a single .NewRouter(*openapi3.Swagger)
  • NOTE: the NewRouter(doc) call now requires that the user ensures doc is valid (doc.Validate() != nil). This used to be asserted.

v0.47.0

Field (*openapi3.SwaggerLoader).LoadSwaggerFromURIFunc of type func(*openapi3.SwaggerLoader, *url.URL) (*openapi3.Swagger, error) was removed after the addition of the field (*openapi3.SwaggerLoader).ReadFromURIFunc of type func(*openapi3.SwaggerLoader, *url.URL) ([]byte, error).