A Go project for handling OpenAPI files. We target:
v2.0 (formerly known as Swagger)v3.0v3.1 Soon! Tracking issue here.Licensed under the MIT License.
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:
net/http"Be sure to check OpenAPI Initiative's great tooling list as well as OpenAPI.Tools.
*openapi3.Schema values for Go types.go run github.com/getkin/kin-openapi/cmd/validate@latest [--circular] [--defaults] [--examples] [--ext] [--patterns] -- <local YAML or JSON file>
Use openapi3.Loader, which resolves all references:
loader := openapi3.NewLoader()
doc, err := loader.LoadFromFile("my-openapi-spec.json")
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
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)
}
By default, the library parses a body of the HTTP request and response
if it has one of the following 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{}.
}
By default, the library checks unique items using the following 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 json.Marshal is used to generate a string that can
be used as a map key which is to 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
}
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.
Paths field of openapi3.T is now a pointerResponses field of openapi3.Operation is now a pointeropenapi3.Paths went from map[string]*PathItem to a struct with an Extensions field and methods: Set, Value, Len, Map, and New*.openapi3.Callback went from map[string]*PathItem to a struct with an Extensions field and methods: Set, Value, Len, Map, and New*.openapi3.Responses went from map[string]*ResponseRef to a struct with an Extensions field and methods: Set, Value, Len, Map, and New*.(openapi3.Responses).Get(int) renamed to (*openapi3.Responses).Status(int)openapi3.RequestBodies (an alias on map[string]*openapi3.ResponseRef) and use it in place of openapi3.Responses for field openapi3.Components.Responses.openapi3filter.DefaultOptions. Use &openapi3filter.Options{} directly instead.email has been removed by default. To use it please call openapi3.DefineStringFormat("email", openapi3.FormatOfStringForEmail).openapi3.T.Components is now a pointer.openapi3.Schema.AdditionalProperties and openapi3.Schema.AdditionalPropertiesAllowed are replaced by openapi3.Schema.AdditionalProperties.Schema and openapi3.Schema.AdditionalProperties.Has respectively.openapi3.ExtensionProps is now just map[string]interface{} and extensions are accessible through the Extensions field.(openapi3.ValidationOptions).ExamplesValidationDisabled has been unexported.(openapi3.ValidationOptions).SchemaFormatValidationEnabled has been unexported.(openapi3.ValidationOptions).SchemaPatternValidationDisabled has been unexported.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.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.openapi3gen.NewSchemaRefForValue changed:
(*Generator).SchemaRefs.doc.Components.Schemas) which gets written to so $ref cycles can be properly handled.openapi2.Swagger to openapi2.T.openapi2conv.FromV3Swagger to openapi2conv.FromV3.openapi2conv.ToV3Swagger to openapi2conv.ToV3.openapi3.LoadSwaggerFromData to openapi3.LoadFromData.openapi3.LoadSwaggerFromDataWithPath to openapi3.LoadFromDataWithPath.openapi3.LoadSwaggerFromFile to openapi3.LoadFromFile.openapi3.LoadSwaggerFromURI to openapi3.LoadFromURI.openapi3.NewSwaggerLoader to openapi3.NewLoader.openapi3.Swagger to openapi3.T.openapi3.SwaggerLoader to openapi3.Loader.openapi3filter.ValidationHandler.SwaggerFile to openapi3filter.ValidationHandler.File.routers.Route.Swagger to routers.Route.Spec.openapi3filter.Route moved to routers (and Route.Handler was dropped. See https://github.com/getkin/kin-openapi/issues/329)openapi3filter.RouteError moved to routers (so did ErrPathNotFound and ErrMethodNotAllowed which are now RouteErrors)FindRoute(...) method now takes only one argument: *http.Requestgetkin/kin-openapi/openapi3filter.Router moved to getkin/kin-openapi/routers/legacyopenapi3filter.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)
NewRouter(doc) call now requires that the user ensures doc is valid (doc.Validate() != nil). This used to be asserted.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).
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket is launching experimental protection for the Hugging Face ecosystem, scanning for malware and malicious payload injections inside model files to prevent silent AI supply chain attacks.
Research
/Security News
The Socket Threat Research Team uncovered a coordinated campaign that floods the Chrome Web Store with 131 rebranded clones of a WhatsApp Web automation extension to spam Brazilian users.
Security News
ENISA’s 2025 Threat Landscape report highlights how AI is reshaping cyber attacks, driving phishing, model poisoning, and software supply chain risks.