package openapi3gen
import "github.com/getkin/kin-openapi/openapi3gen"
Package openapi3gen generates OpenAPIv3 JSON schemas from Go types.
Code:play
Output: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)
}
{
"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
- 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 ¶
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 (*Generator) GenerateSchemaRef ¶
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 ""
Source Files ¶
- Version
- v0.81.0
- Published
- Nov 8, 2021
- Platform
- darwin/amd64
- Imports
- 8 packages
- Last checked
- 5 minutes ago –
Tools for package owners.