reflectopenapi

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2023 License: Apache-2.0 Imports: 15 Imported by: 1

README

reflect-openapi

Define openapi.json with reflect package.

examples

Some examples are here. ./_examples

used by

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var FORCE bool

Functions

func NewDoc 

func NewDoc() (*openapi3.T, error)

func NewDocFromSkeleton 

func NewDocFromSkeleton(spec []byte) (*openapi3.T, error)

TODO: add api function

Types

type Binder 

type Binder interface {
	BindSchemas(doc *openapi3.T)
}

type Config added in v0.0.2 

type Config struct {
	*TagNameOption
	Fset *token.FileSet
	Info *info.Info // go/types.Info like object (tracking metadata)

	Doc    *openapi3.T
	Loaded bool // if true, skip registerType() and registerFunc() actions

	Resolver  Resolver
	Selector  Selector
	Extractor Extractor

	StrictSchema        bool // if true, use `{additionalProperties: false}` as default
	SkipValidation      bool // if true, skip validation for api doc definition
	SkipExtractComments bool // if true, skip extracting comments as a description

	EnableAutoTag bool // if true, adding package name as tag

	DisableInputRef  bool
	DisableOutputRef bool

	DefaultError            interface{}
	DefaultErrorExample     interface{}
	IsRequiredCheckFunction func(reflect.StructTag) bool // handling required, default is always false
	GoPositionFunc          func(*token.FileSet, *shape.Func) string
}
Example 
package main

import (
	"context"
	"encoding/json"
	"os"

	"github.com/getkin/kin-openapi/openapi3"
	reflectopenapi "github.com/podhmo/reflect-openapi"
)

// This is Owner of something
type Owner struct {
	// name of owner
	Name string `json:"name" openapi-override:"{'pattern': '^[A-Z][-A-Za-z]+$'}"`
	Age  int    `json:"age,omitempty"` // age of owner
}

// input parameters
type ListOwnerInput struct {
	// sort option
	Sort string `json:"sort" in:"query" openapi-override:"{'enum': ['desc', 'asc'], 'default': 'asc'}"`
}

// Returns list of owners.
func ListOwner(ctx context.Context, input ListOwnerInput) ([]*Owner, error) {
	return nil, nil
}

func main() {
	c := reflectopenapi.Config{
		TagNameOption: &reflectopenapi.TagNameOption{
			NameTag:        "json",
			ParamTypeTag:   "in",
			DescriptionTag: "description",
			OverrideTag:    "openapi-override",
		},
		SkipValidation: true,
		EnableAutoTag:  true,
		Extractor:      shapeCfg,
	}
	doc, _ := c.BuildDoc(context.Background(), func(m *reflectopenapi.Manager) {
		m.RegisterFunc(ListOwner).After(func(op *openapi3.Operation) {
			m.Doc.AddOperation("/owners", "GET", op)
		})
	})
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "@@")
	enc.Encode(doc)
}

Output:

{
@@"components": {
@@@@"schemas": {
@@@@@@"Owner": {
@@@@@@@@"description": "This is Owner of something",
@@@@@@@@"properties": {
@@@@@@@@@@"age": {
@@@@@@@@@@@@"description": "age of owner",
@@@@@@@@@@@@"type": "integer"
@@@@@@@@@@},
@@@@@@@@@@"name": {
@@@@@@@@@@@@"description": "name of owner",
@@@@@@@@@@@@"pattern": "^[A-Z][-A-Za-z]+$",
@@@@@@@@@@@@"type": "string"
@@@@@@@@@@}
@@@@@@@@},
@@@@@@@@"required": [
@@@@@@@@@@"name"
@@@@@@@@],
@@@@@@@@"title": "Owner",
@@@@@@@@"type": "object"
@@@@@@}
@@@@}
@@},
@@"info": {
@@@@"title": "Sample API",
@@@@"version": "0.0.0"
@@},
@@"openapi": "3.0.0",
@@"paths": {
@@@@"/owners": {
@@@@@@"get": {
@@@@@@@@"description": "Returns list of owners.",
@@@@@@@@"operationId": "github.com/podhmo/reflect-openapi_test.ListOwner",
@@@@@@@@"parameters": [
@@@@@@@@@@{
@@@@@@@@@@@@"description": "sort option",
@@@@@@@@@@@@"in": "query",
@@@@@@@@@@@@"name": "sort",
@@@@@@@@@@@@"schema": {
@@@@@@@@@@@@@@"default": "asc",
@@@@@@@@@@@@@@"enum": [
@@@@@@@@@@@@@@@@"desc",
@@@@@@@@@@@@@@@@"asc"
@@@@@@@@@@@@@@],
@@@@@@@@@@@@@@"type": "string"
@@@@@@@@@@@@}
@@@@@@@@@@}
@@@@@@@@],
@@@@@@@@"responses": {
@@@@@@@@@@"200": {
@@@@@@@@@@@@"content": {
@@@@@@@@@@@@@@"application/json": {
@@@@@@@@@@@@@@@@"schema": {
@@@@@@@@@@@@@@@@@@"items": {
@@@@@@@@@@@@@@@@@@@@"$ref": "#/components/schemas/Owner"
@@@@@@@@@@@@@@@@@@},
@@@@@@@@@@@@@@@@@@"type": "array"
@@@@@@@@@@@@@@@@}
@@@@@@@@@@@@@@}
@@@@@@@@@@@@},
@@@@@@@@@@@@"description": ""
@@@@@@@@@@},
@@@@@@@@@@"default": {
@@@@@@@@@@@@"description": ""
@@@@@@@@@@}
@@@@@@@@},
@@@@@@@@"summary": "Returns list of owners.",
@@@@@@@@"tags": [
@@@@@@@@@@"reflect-openapi_test"
@@@@@@@@]
@@@@@@}
@@@@}
@@},
@@"servers": [
@@@@{
@@@@@@"description": "local development server",
@@@@@@"url": "http://localhost:8888"
@@@@}
@@],
@@"tags": [
@@@@{
@@@@@@"name": "reflect-openapi_test"
@@@@}
@@]
}

func (*Config) BuildDoc added in v0.0.2 

func (c *Config) BuildDoc(ctx context.Context, use func(m *Manager)) (*openapi3.T, error)

func (*Config) DefaultExtractor added in v0.0.6 

func (c *Config) DefaultExtractor() Extractor

func (*Config) DefaultResolver added in v0.0.6 

func (c *Config) DefaultResolver() Resolver

func (*Config) DefaultSelector added in v0.0.6 

func (c *Config) DefaultSelector() Selector

func (*Config) EmitDoc added in v0.0.3 

func (c *Config) EmitDoc(use func(m *Manager))

func (*Config) NewManager added in v0.0.13 

func (c *Config) NewManager() (*Manager, func(ctx context.Context) error, error)

type DefaultSelector added in v0.0.6 

type DefaultSelector struct {
	FirstParamInputSelector
	FirstParamOutputSelector
}

type Direction added in v0.2.1 

type Direction string
const (
	DirectionInput     Direction = "input"
	DirectionOutput    Direction = "output"
	DirectionInternal  Direction = "internal"
	DirectionParameter Direction = "parameter"
)

type Extractor added in v0.0.6 

type Extractor interface {
	Extract(interface{}) *shape.Shape
}

type FirstParamInputSelector added in v0.0.6 

type FirstParamInputSelector struct{}

func (*FirstParamInputSelector) SelectInput added in v0.0.6 

func (s *FirstParamInputSelector) SelectInput(fn *shape.Func) (*shape.Shape, string)

type FirstParamOutputSelector added in v0.0.6 

type FirstParamOutputSelector struct{}

func (*FirstParamOutputSelector) SelectOutput added in v0.0.6 

func (s *FirstParamOutputSelector) SelectOutput(fn *shape.Func) (*shape.Shape, string)
type Header struct {
	Name        string
	Description string
	Example     string
}

type Manager added in v0.0.2 

type Manager struct {
	Visitor  *Visitor // TODO: changes to unexported field
	Resolver Resolver
	Actions  []*registerAction

	Doc *openapi3.T
}

func (*Manager) RegisterFunc added in v0.0.9 

func (m *Manager) RegisterFunc(fn interface{}, modifiers ...func(*openapi3.Operation)) *RegisterFuncAction

func (*Manager) RegisterFuncText added in v0.3.0 

func (m *Manager) RegisterFuncText(fn interface{}, contentType string, modifiers ...func(*openapi3.Operation)) *RegisterFuncAction

func (*Manager) RegisterInterception added in v0.2.0 

func (m *Manager) RegisterInterception(rt reflect.Type, intercept func(*shape.Shape) *openapi3.Schema)

func (*Manager) RegisterType added in v0.0.9 

func (m *Manager) RegisterType(ob interface{}, modifiers ...func(*openapi3.SchemaRef)) *RegisterTypeAction

type MergeParamsInputSelector added in v0.0.6 

type MergeParamsInputSelector struct {
	// contains filtered or unexported fields
}

func (*MergeParamsInputSelector) NeedTransformer added in v0.2.0 

func (s *MergeParamsInputSelector) NeedTransformer(t *Transformer)

func (*MergeParamsInputSelector) SelectInput added in v0.0.6 

func (s *MergeParamsInputSelector) SelectInput(fn *shape.Func) (*shape.Shape, string)

type NameStore added in v0.0.9 

type NameStore struct {
	Prefix     string
	OnConflict func(*RefPair, int)
	// contains filtered or unexported fields
}

func NewNameStore added in v0.0.9 

func NewNameStore() *NameStore

func (*NameStore) BindSchemas added in v0.0.9 

func (ns *NameStore) BindSchemas(doc *openapi3.T)

func (*NameStore) GetOrCreatePair added in v0.0.9 

func (ns *NameStore) GetOrCreatePair(v *openapi3.Schema, name string, shape *shape.Shape) *RefPair

type NoRefResolver 

type NoRefResolver struct {
	AdditionalPropertiesAllowed *bool // set as Config.StrictSchema
}

func (*NoRefResolver) ResolveParameter 

func (r *NoRefResolver) ResolveParameter(v *openapi3.Parameter, s *shape.Shape) *openapi3.ParameterRef

func (*NoRefResolver) ResolveRequestBody 

func (r *NoRefResolver) ResolveRequestBody(v *openapi3.RequestBody, s *shape.Shape) *openapi3.RequestBodyRef

func (*NoRefResolver) ResolveResponse 

func (r *NoRefResolver) ResolveResponse(v *openapi3.Response, s *shape.Shape) *openapi3.ResponseRef

func (*NoRefResolver) ResolveSchema 

func (r *NoRefResolver) ResolveSchema(v *openapi3.Schema, s *shape.Shape, typ Direction) *openapi3.SchemaRef

type RefPair added in v0.0.9 

type RefPair struct {
	Name  string
	Shape *shape.Shape

	Def *openapi3.SchemaRef
	Ref *openapi3.SchemaRef
}

type RegisterFuncAction added in v0.0.9 

type RegisterFuncAction struct {
	// contains filtered or unexported fields
}

func (*RegisterFuncAction) After added in v0.0.9 

func (a *RegisterFuncAction) After(f func(*openapi3.Operation)) *RegisterFuncAction

func (*RegisterFuncAction) AnotherError added in v0.3.0 

func (a *RegisterFuncAction) AnotherError(code int, value interface{}, description string) *RegisterFuncAction

func (*RegisterFuncAction) Before added in v0.2.1 

func (a *RegisterFuncAction) Before(f func(*shape.Func)) *RegisterFuncAction

func (*RegisterFuncAction) DefaultInput added in v0.2.1 

func (a *RegisterFuncAction) DefaultInput(value interface{}) *RegisterFuncAction

func (*RegisterFuncAction) Description added in v0.1.0 

func (a *RegisterFuncAction) Description(description string) *RegisterFuncAction

func (*RegisterFuncAction) Error added in v0.3.0 

func (a *RegisterFuncAction) Error(value interface{}, description string) *RegisterFuncAction

func (*RegisterFuncAction) Example added in v0.1.0 

func (a *RegisterFuncAction) Example(code int, mime string, title, description string, value interface{}) *RegisterFuncAction

func (*RegisterFuncAction) Headers added in v0.3.0 

func (a *RegisterFuncAction) Headers(values ...Header) *RegisterFuncAction

func (*RegisterFuncAction) Status added in v0.1.0 

func (a *RegisterFuncAction) Status(code int) *RegisterFuncAction

func (*RegisterFuncAction) Tags added in v0.3.0 

func (a *RegisterFuncAction) Tags(tags ...string) *RegisterFuncAction

type RegisterTypeAction added in v0.0.9 

type RegisterTypeAction struct {
	// contains filtered or unexported fields
}

func (*RegisterTypeAction) After added in v0.0.9 

func (a *RegisterTypeAction) After(f func(*openapi3.Schema)) *RegisterTypeAction

func (*RegisterTypeAction) Before added in v0.1.0 

func (a *RegisterTypeAction) Before(f func(*shape.Shape)) *RegisterTypeAction

func (*RegisterTypeAction) Default added in v0.1.0 

func (a *RegisterTypeAction) Default(value interface{}) *RegisterTypeAction

func (*RegisterTypeAction) Description added in v0.1.0 

func (a *RegisterTypeAction) Description(description string) *RegisterTypeAction

func (*RegisterTypeAction) Enum added in v0.1.0 

func (a *RegisterTypeAction) Enum(values ...interface{}) *RegisterTypeAction

func (*RegisterTypeAction) Example added in v0.1.0 

func (a *RegisterTypeAction) Example(value interface{}) *RegisterTypeAction

type Resolver 

type Resolver interface {
	ResolveSchema(v *openapi3.Schema, s *shape.Shape, typ Direction) *openapi3.SchemaRef
	ResolveParameter(v *openapi3.Parameter, s *shape.Shape) *openapi3.ParameterRef
	ResolveRequestBody(v *openapi3.RequestBody, s *shape.Shape) *openapi3.RequestBodyRef
	ResolveResponse(v *openapi3.Response, s *shape.Shape) *openapi3.ResponseRef
}

type Selector added in v0.0.6 

type Selector interface {
	SelectInput(*shape.Func) (*shape.Shape, string)
	SelectOutput(*shape.Func) (*shape.Shape, string)
}

type TagNameOption added in v0.2.0 

type TagNameOption struct {
	NameTag        string
	RequiredTag    string
	ParamTypeTag   string
	OverrideTag    string
	DescriptionTag string

	XNewTypeTag string
}

func DefaultTagNameOption added in v0.2.0 

func DefaultTagNameOption() *TagNameOption

type Transformer 

type Transformer struct {
	Resolver
	Selector Selector

	Extractor     Extractor
	TagNameOption TagNameOption

	CacheHit int

	IsRequired func(reflect.StructTag) bool

	Fset           *token.FileSet
	GoPositionFunc func(fset *token.FileSet, fn *shape.Func) string
	// contains filtered or unexported fields
}

func (*Transformer) Builtin 

func (t *Transformer) Builtin() *Transformer

func (*Transformer) RegisterInterception added in v0.0.2 

func (t *Transformer) RegisterInterception(rt reflect.Type, intercept func(*shape.Shape) *openapi3.Schema)

func (*Transformer) Transform 

func (t *Transformer) Transform(s *shape.Shape) interface{}

type UseRefResolver 

type UseRefResolver struct {
	*NameStore // for Binder

	DisableInputRef             bool
	DisableOutputRef            bool
	AdditionalPropertiesAllowed *bool // set as Config.StrictSchema
}

func (*UseRefResolver) ResolveParameter 

func (r *UseRefResolver) ResolveParameter(v *openapi3.Parameter, s *shape.Shape) *openapi3.ParameterRef

func (*UseRefResolver) ResolveRequestBody 

func (r *UseRefResolver) ResolveRequestBody(v *openapi3.RequestBody, s *shape.Shape) *openapi3.RequestBodyRef

func (*UseRefResolver) ResolveResponse 

func (r *UseRefResolver) ResolveResponse(v *openapi3.Response, s *shape.Shape) *openapi3.ResponseRef

func (*UseRefResolver) ResolveSchema 

func (r *UseRefResolver) ResolveSchema(v *openapi3.Schema, s *shape.Shape, direction Direction) (ref *openapi3.SchemaRef)

type Visitor 

type Visitor struct {
	*Transformer

	Doc        *openapi3.T
	Schemas    map[int]*openapi3.Schema
	Operations map[int]*openapi3.Operation

	EnableAutoTag bool
}

not visitor pattern

func NewVisitor 

func NewVisitor(tagNameOption TagNameOption, resolver Resolver, selector Selector, extractor Extractor) *Visitor

func (*Visitor) VisitFunc 

func (v *Visitor) VisitFunc(in *shape.Shape, modifiers ...func(*openapi3.Operation)) *openapi3.Operation

func (*Visitor) VisitType 

func (v *Visitor) VisitType(in *shape.Shape, modifiers ...func(*openapi3.Schema)) *openapi3.SchemaRef

Source Files

View all Source files

Directories

Path Synopsis
pkg
jsonequal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.