[opensourcedex]

kin-openapi is a free, open source documentation & knowledge base project written in Go and released under MIT. It has 3,292 GitHub stars, 512 forks and 114 open issues, and was last pushed 38 hours ago. On this registry it ranks #41 of 91 tracked projects in Documentation & Knowledge Base, with 5 head-to-head comparisons available.

CI Go Reference Join Gitter Chat Channel - inspect.software

Introduction

A Go project for handling OpenAPI files. We target:

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:

Alternatives

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

readme truncated — read the full docs on github

Frequently asked questions

Is kin-openapi free to use?

kin-openapi is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does kin-openapi do?

OpenAPI 3.0 and 3.1 and 3.2 (and Swagger v2) implementation for Go (parsing, converting, validation, and more)

What is kin-openapi written in?

kin-openapi is primarily written in Go. Its source is publicly available at https://github.com/getkin/kin-openapi, and it has 3,292 GitHub stars.