README.md

Overview

This library provides packages for dealing with OpenAPI specifications.

Status

Current

• Reads and writes OpenAPI version 3.0 documents
• Reads and writes OpenAPI version 2.0 documents and converts 2.0 -> 3.0 and 3.0->2.0.
  • Does NOT support all features.
• Validates:
  • That a Go value matches OpenAPI 3.0 schema object
  • That HTTP request matches OpenAPI operation object
  • That HTTP response matches OpenAPI 3.0 operation object
• Generates JSON schemas for Go types.

TODO

• More tests

Dependencies

• Go 1.7 or greater.
• No other dependencies!

License

• MIT License

Alternatives

• go-openapi
  • Provides a stable and well-tested implementation of OpenAPI version 2.
• See this list.

Packages

• jsoninfo
  • Provides information and functions for marshalling/unmarshalling JSON. The purpose is a clutter-free implementation of JSON references and OpenAPI extension properties.
• openapi2
  • Parses/writes OpenAPI 2.
• openapi2conv
  • Converts OpenAPI 2 specification into OpenAPI 3 specification.
• openapi3
  • Parses/writes OpenAPI 3. Includes OpenAPI schema / JSON schema valdation.
• openapi3filter
  • Validates that HTTP request and HTTP response match an OpenAPI specification file.
• openapi3gen
  • Generates OpenAPI 3 schemas for Go types.
• pathpattern
  • Support for OpenAPI style path patterns.

Getting started

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

Having extension properties in your own structs

The package jsoninfo marshals/unmarshal JSON extension properties ("x-someExtension")

Usage looks like:

type Example struct {
  // Allow extension properties ("x-someProperty")
  openapi3.ExtensionProps

  // Normal properties
  SomeField float64
}

func (example *Example) MarshalJSON() ([]byte, error) {
  return jsoninfo.MarshalStrictStruct(example)
}

func (example *Example) UnmarshalJSON(data []byte) error {
  return jsoninfo.UnmarshalStrictStruct(data, example)
}