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).

This is the beginning of the README. Read the rest at the original. Read the full README ↗