Skip to content

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

License

Notifications You must be signed in to change notification settings

slessard/kin-openapi

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CI Go Report Card GoDoc Join Gitter Chat Channel -

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!

Be sure to give back to this project like our sponsors:

Speakeasy

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 (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 openapi3.Loader, which resolves all references:

doc, err := openapi3.NewLoader().LoadFromFile("swagger.json")

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 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 io.Reader, h http.Header, schema *openapi3.SchemaRef, encFn openapi3filter.EncodingFn) (decoded interface{}, err 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.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 getkin#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 <router package>.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).

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Go 100.0%