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 UseAllExportedFields() Option

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 UseAllExportedFields

func UseAllExportedFields() Option

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