Introduction
A Go project for handling OpenAPI files. We target:
- OpenAPI
v2.0
(formerly known as Swagger) - OpenAPI
v3.0
- OpenAPI
v3.1
Soon! Tracking issue here.
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:
Here's some projects that depend on kin-openapi:
- 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/deepmap/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
- go-swagger stated OpenAPIv3 won't be supported
- swaggo has an open issue on OpenAPIv3
- go-openapi's spec3
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.
- Generates
Some recipes
Validating an OpenAPI document
go run github.com/getkin/kin-openapi/cmd/validate@latest [--circular] [--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("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, []interface{}, or map[string]interface{}.
}
Custom function to check uniqueness of array items
By default, 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
}
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.
Sub-v0 breaking API changes
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 callopenapi3.DefineStringFormat("email", openapi3.FormatOfStringForEmail)
. - Field
openapi3.T.Components
is now a pointer. - Fields
openapi3.Schema.AdditionalProperties
andopenapi3.Schema.AdditionalPropertiesAllowed
are replaced byopenapi3.Schema.AdditionalProperties.Schema
andopenapi3.Schema.AdditionalProperties.Has
respectively. - Type
openapi3.ExtensionProps
is now justmap[string]interface{}
and extensions are accessible through theExtensions
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
tofunc (*_) Validate(ctx context.Context, opts ...ValidationOption) error
. openapi3.WithValidationOptions(ctx context.Context, opts *ValidationOptions) context.Context
prototype changed toopenapi3.WithValidationOptions(ctx context.Context, opts ...ValidationOption) context.Context
.
v0.101.0
openapi3.SchemaFormatValidationDisabled
has been removed in favour of an optionopenapi3.EnableSchemaFormatValidation()
passed toopenapi3.T.Validate
. The default behaviour is also now to not validate formats, as the OpenAPI spec mentions theformat
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.
- It no longer returns a map but that is still accessible under the field
v0.61.0
- Renamed
openapi2.Swagger
toopenapi2.T
. - Renamed
openapi2conv.FromV3Swagger
toopenapi2conv.FromV3
. - Renamed
openapi2conv.ToV3Swagger
toopenapi2conv.ToV3
. - Renamed
openapi3.LoadSwaggerFromData
toopenapi3.LoadFromData
. - Renamed
openapi3.LoadSwaggerFromDataWithPath
toopenapi3.LoadFromDataWithPath
. - Renamed
openapi3.LoadSwaggerFromFile
toopenapi3.LoadFromFile
. - Renamed
openapi3.LoadSwaggerFromURI
toopenapi3.LoadFromURI
. - Renamed
openapi3.NewSwaggerLoader
toopenapi3.NewLoader
. - Renamed
openapi3.Swagger
toopenapi3.T
. - Renamed
openapi3.SwaggerLoader
toopenapi3.Loader
. - Renamed
openapi3filter.ValidationHandler.SwaggerFile
toopenapi3filter.ValidationHandler.File
. - Renamed
routers.Route.Swagger
torouters.Route.Spec
.
v0.51.0
- Type
openapi3filter.Route
moved torouters
(andRoute.Handler
was dropped. See #329) - Type
openapi3filter.RouteError
moved torouters
(so didErrPathNotFound
andErrMethodNotAllowed
which are nowRouteError
s) - Routers'
FindRoute(...)
method now takes only one argument:*http.Request
getkin/kin-openapi/openapi3filter.Router
moved togetkin/kin-openapi/routers/legacy
openapi3filter.NewRouter()
and its relatedWithSwaggerFromFile(string)
,WithSwagger(*openapi3.Swagger)
,AddSwaggerFromFile(string)
andAddSwagger(*openapi3.Swagger)
are all replaced with a single<router package>.NewRouter(*openapi3.Swagger)
- NOTE: the
NewRouter(doc)
call now requires that the user ensuresdoc
is valid (doc.Validate() != nil
). This used to be asserted.
- NOTE: the
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)
.