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"
• (Feel free to add your project by creating an issue or a pull request)

Alternative projects

• go-openapi
  • Supports OpenAPI version 2.
• See this 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
• 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.String())
  if err!=nil {
    return nil, err
  }

  // Get OpenAPI 3 operation
  return route.Operation
}

Validating HTTP requests/responses

import (
  "net/http"

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

var router = openapi3filter.NewRouter().WithSwaggerFromFile("swagger.json")

func ValidateRequest(req *http.Request) {
  openapi3filter.ValidateRequest(nil, &openapi3filter.ValidateRequestInput {
    Request: req,
    Router:  router,
  })

  // Get response

  openapi3filter.ValidateResponse(nil, &openapi3filter.ValidateResponseInput {
    // ...
  })
}