![Join Gitter Chat Channel -](https://badges.gitter.im/getkin/kin.svg)
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:
Alternative projects
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
- openapi3gen (godoc)
- Generates
*openapi3.Schema
values for Go types.
- pathpattern (godoc)
- Matches strings with OpenAPI path patterns ("/path/{parameter}")
Some recipes
Loading OpenAPI document
Use SwaggerLoader
, which resolves all JSON references:
swagger, err := openapi3.NewSwaggerLoader().LoadSwaggerFromFile("swagger.json")
Getting OpenAPI operation that matches request
func GetOperation(httpRequest *http.Request) (*openapi3.Operation, error) {
// Load Swagger file
router := openapi3filter.NewRouter().WithSwaggerFromFile("swagger.json")
// Find route
route, _, err := router.FindRoute("GET", req.URL)
if err != nil {
return nil, err
}
// Get OpenAPI 3 operation
return route.Operation
}
Validating HTTP requests/responses
package main
import (
"bytes"
"context"
"encoding/json"
"log"
"net/http"
"github.com/errorboi/kin-openapi-playground/openapi3filter"
)
func main() {
router := openapi3filter.NewRouter().WithSwaggerFromFile("swagger.json")
ctx := context.TODO()
httpReq, _ := http.NewRequest(http.MethodGet, "/items", nil)
// Find route
route, pathParams, _ := router.FindRoute(httpReq.Method, httpReq.URL)
// 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 for check uniqueness of JSON array
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 {
// The input slice is coverted from a JSON string, there shall
// have no error when covert it back.
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 JSON objects or JSON arraies. 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(array in JSON)
}