openapi3gen

Documentation

Overview

Package openapi3gen generates OpenAPIv3 JSON schemas from Go types.

Example

package main

import (
	"encoding/json"
	"fmt"
	"time"

	"github.com/getkin/kin-openapi/openapi3gen"
)

type (
	SomeStruct struct {
		Bool    bool                      `json:"bool"`
		Int     int                       `json:"int"`
		Int64   int64                     `json:"int64"`
		Float64 float64                   `json:"float64"`
		String  string                    `json:"string"`
		Bytes   []byte                    `json:"bytes"`
		JSON    json.RawMessage           `json:"json"`
		Time    time.Time                 `json:"time"`
		Slice   []SomeOtherType           `json:"slice"`
		Map     map[string]*SomeOtherType `json:"map"`

		Struct struct {
			X string `json:"x"`
		} `json:"struct"`

		EmptyStruct struct {
			Y string
		} `json:"structWithoutFields"`

		Ptr *SomeOtherType `json:"ptr"`
	}

	SomeOtherType string
)

func main() {
	schemaRef, refsMap, err := openapi3gen.NewSchemaRefForValue(&SomeStruct{})
	if err != nil {
		panic(err)
	}

	if len(refsMap) != 15 {
		panic(fmt.Sprintf("unintended len(refsMap) = %d", len(refsMap)))
	}

	data, err := json.MarshalIndent(schemaRef, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s\n", data)
}

Output:

{
  "properties": {
    "bool": {
      "type": "boolean"
    },
    "bytes": {
      "format": "byte",
      "type": "string"
    },
    "float64": {
      "format": "double",
      "type": "number"
    },
    "int": {
      "type": "integer"
    },
    "int64": {
      "format": "int64",
      "type": "integer"
    },
    "json": {},
    "map": {
      "additionalProperties": {
        "type": "string"
      },
      "type": "object"
    },
    "ptr": {
      "type": "string"
    },
    "slice": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "string": {
      "type": "string"
    },
    "struct": {
      "properties": {
        "x": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "structWithoutFields": {},
    "time": {
      "format": "date-time",
      "type": "string"
    }
  },
  "type": "object"
}

Index

• Variables
• func NewSchemaRefForValue(value interface{}, opts ...Option) (*openapi3.SchemaRef, map[*openapi3.SchemaRef]int, error)
• type CycleError
  • func (err *CycleError) Error() string
• type Generator
  • func NewGenerator(opts ...Option) *Generator
  • func (g *Generator) GenerateSchemaRef(t reflect.Type) (*openapi3.SchemaRef, error)
• type Option
  • func SchemaCustomizer(sc SchemaCustomizerFn) Option
  • func ThrowErrorOnCycle() Option
  • func UseAllExportedFields() Option
• type SchemaCustomizerFn

Examples

• Package

Variables

var RefSchemaRef = openapi3.NewSchemaRef("Ref",
	openapi3.NewObjectSchema().WithProperty("$ref", openapi3.NewStringSchema().WithMinLength(1)))

Functions

func NewSchemaRefForValue

func NewSchemaRefForValue(value interface{}, opts ...Option) (*openapi3.SchemaRef, map[*openapi3.SchemaRef]int, error)

NewSchemaRefForValue uses reflection on the given value to produce a SchemaRef.

Types

type CycleError

type CycleError struct{}

CycleError indicates that a type graph has one or more possible cycles.

func (*CycleError) Error

func (err *CycleError) Error() string

type Generator

type Generator struct {
	Types map[reflect.Type]*openapi3.SchemaRef

	// SchemaRefs contains all references and their counts.
	// If count is 1, it's not ne
	// An OpenAPI identifier has been assigned to each.
	SchemaRefs map[*openapi3.SchemaRef]int
	// contains filtered or unexported fields
}

func NewGenerator

func NewGenerator(opts ...Option) *Generator

func (*Generator) GenerateSchemaRef

func (g *Generator) GenerateSchemaRef(t reflect.Type) (*openapi3.SchemaRef, error)

type Option

type Option func(*generatorOpt)

Option allows tweaking SchemaRef generation

func SchemaCustomizer

func SchemaCustomizer(sc SchemaCustomizerFn) Option

SchemaCustomizer allows customization of the schema that is generated for a field, for example to support an additional tagging scheme

func ThrowErrorOnCycle

func ThrowErrorOnCycle() Option

ThrowErrorOnCycle changes the default behavior of creating cycle refs to instead error if a cycle is detected.

func UseAllExportedFields

func UseAllExportedFields() Option

UseAllExportedFields changes the default behavior of only generating schemas for struct fields with a JSON tag.

type SchemaCustomizerFn

type SchemaCustomizerFn func(name string, t reflect.Type, tag reflect.StructTag, schema *openapi3.Schema) error

SchemaCustomizerFn is a callback function, allowing the OpenAPI schema definition to be updated with additional properties during the generation process, based on the name of the field, the Go type, and the struct tags. name will be "_root" for the top level object, and tag will be ""