kin-openapi

README

Introduction

A Go project for handling OpenAPI files. We target the latest OpenAPI version (currently 3), but the project contains support for older OpenAPI versions too.

Licensed under the MIT License.

Contributors and users

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

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

• github.com/getkin/kin - "A configurable backend"
• github.com/danielgtaylor/apisprout - "Lightweight, blazing fast, cross-platform OpenAPI 3 mock server with validation"
• github.com/deepmap/oapi-codegen - Generate Go server boilerplate from an OpenAPI 3 spec
• 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 - "Goa is a framework for building micro-services and APIs in Go using a unique design-first approach."
• (Feel free to add your project by creating an issue or a pull request)

Alternatives

• go-swagger stated OpenAPIv3 won't be supported
• swaggo has an open issue on OpenAPIv3
• go-openapi's spec3
  • an iteration on spec (for OpenAPIv2)
  • see README for the missing parts
• See https://github.com/OAI's great tooling list

Structure

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

Some recipes

Loading OpenAPI document

Use SwaggerLoader, which resolves all references:

swagger, err := openapi3.NewSwaggerLoader().LoadSwaggerFromFile("swagger.json")

Getting OpenAPI operation that matches request

loader := openapi3.NewSwaggerLoader()
spec, _ := loader.LoadSwaggerFromData([]byte(`...`))
_ := spec.Validate(loader.Context)
router, _ := openapi3filter.NewRouter(spec)
route, pathParams, _ := router.FindRoute(httpRequest)
// Do something with route.Operation

Validating HTTP requests/responses

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"log"
	"net/http"

	"github.com/getkin/kin-openapi/openapi3filter"
)

func main() {
	ctx := context.Background()
	loader := &openapi3.SwaggerLoader{Context: ctx}
	spec, _ := loader.LoadSwaggerFromFile("openapi3_spec.json")
	_ := spec.Validate(ctx)
	router, _ := openapi3filter.NewRouter(spec)
	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,
	}
	if err := openapi3filter.ValidateRequest(ctx, requestValidationInput); err != nil {
		panic(err)
	}

	var (
		respStatus      = 200
		respContentType = "application/json"
		respBody        = bytes.NewBufferString(`{}`)
	)

	log.Println("Response:", respStatus)
	responseValidationInput := &openapi3filter.ResponseValidationInput{
		RequestValidationInput: requestValidationInput,
		Status:                 respStatus,
		Header:                 http.Header{"Content-Type": []string{respContentType}},
	}
	if respBody != nil {
		data, _ := json.Marshal(respBody)
		responseValidationInput.SetBodyBytes(data)
	}

	// Validate response.
	if err := openapi3filter.ValidateResponse(ctx, responseValidationInput); err != nil {
		panic(err)
	}
}

Custom content type for body of HTTP request/response

By default, the library parses a body of HTTP request and response if it has one of the next content types: "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 []byte) (interface{}, error) {
	// Decode body to a primitive, []inteface{}, or map[string]interface{}.
}

Custom function to check uniqueness of array items

By defaut, the library check unique items by below predefined function

func isSliceOfUniqueItems(xs []interface{}) 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 using json.Marshal to generate a string can be used as a map key which is to support 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 []interface{}) bool {
	// Check the uniqueness of the input slice
}

Sub-v0 breaking API changes

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