README

Build Status Go Report Card GoDoc Join Gitter Chat Channel -

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.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 {
    // ...
  })
}

Expand ▾ Collapse ▴

Directories

Path Synopsis
Package jsoninfo provides information and functions for marshalling/unmarshalling JSON.
Package jsoninfo provides information and functions for marshalling/unmarshalling JSON.
Package openapi2 parses and writes OpenAPI 2 specifications.
Package openapi2 parses and writes OpenAPI 2 specifications.
Package openapi2conv converts an OpenAPI v2 specification to v3.
Package openapi2conv converts an OpenAPI v2 specification to v3.
Package openapi3 parses and writes OpenAPI 3 specifications.
Package openapi3 parses and writes OpenAPI 3 specifications.
Package openapi3filter validates that requests and inputs request an OpenAPI 3 specification file.
Package openapi3filter validates that requests and inputs request an OpenAPI 3 specification file.
Package openapi3gen generates OpenAPI 3 schemas for Go types.
Package openapi3gen generates OpenAPI 3 schemas for Go types.
Package pathpattern implements path matching.
Package pathpattern implements path matching.