openapi

package
v0.14.1 Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2024 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIOperation 

type APIOperation interface {
	Marshal() ([]byte, error)
	Unmarshal(data []byte, v interface{}) error
	GetTags() []string
	GetSummary() string
	GetDescription() string
	GetID() string
	GetParameters() []*ParameterOrRef
	GetRequestBody() *RequestBody
	GetResponses() Responses
	GetDeprecated() bool
	GetServers() []*Server
	GetSecurity() []map[string]interface{}
}

type ApiKeyAuth added in v0.13.7 

type ApiKeyAuth struct {
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
	In   string `json:"in,omitempty" yaml:"in,omitempty"`
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
}

type Components 

type Components struct {
	Schemas        map[string]*SchemaOrRef    `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	SecurityScheme map[string]interface{}     `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
	Responses      map[string]*ResponseOrRef  `json:"responses,omitempty" yaml:"responses,omitempty"`
	Parameters     map[string]*ParameterOrRef `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Examples       map[string]*ExampleOrRef   `json:"examples,omitempty" yaml:"examples,omitempty"`
	Headers        map[string]*HeaderOrRef    `json:"headers,omitempty" yaml:"headers,omitempty"`
}

Components holds a set of reusable objects for different ascpects of the specification.

type Contact 

type Contact struct {
	Name  string `json:"name,omitempty" yaml:"name,omitempty"`
	URL   string `json:"url,omitempty" yaml:"url,omitempty"`
	Email string `json:"email,omitempty" yaml:"email,omitempty"`
}

Contact represents the the contact informations exposed for an API.

type DataType 

type DataType interface {
	Type() string
	Format() string
}

DataType is the interface implemented by types that can describe their OAS3 data type and format.

func DataTypeFromType 

func DataTypeFromType(t reflect.Type) DataType

DataTypeFromType returns a DataType for the given type.

type Encoding 

type Encoding struct {
	ContentType   string                  `json:"contentType,omitempty" yaml:"contentType,omitempty"`
	Headers       map[string]*HeaderOrRef `json:"headers,omitempty" yaml:"headers,omitempty"`
	Style         string                  `json:"style,omitempty" yaml:"style,omitempty"`
	Explode       bool                    `json:"explode,omitempty" yaml:"explode,omitempty"`
	AllowReserved bool                    `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
}

Encoding represents a single encoding definition applied to a single schema property.

type Example 

type Example struct {
	Summary       string      `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description   string      `json:"description,omitempty" yaml:"description,omitempty"`
	Value         interface{} `json:"value,omitempty" yaml:"value,omitempty"`
	ExternalValue string      `json:"externalValue,omitempty" yaml:"externalValue,omitempty"`
}

Example represents the exanple of a media type.

type ExampleOrRef 

type ExampleOrRef struct {
	*Example
	*Reference
}

ExampleOrRef represents an Example that can be inlined or referenced in the API description.

func (*ExampleOrRef) MarshalYAML 

func (eor *ExampleOrRef) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for ExampleOrRef.

type FieldError 

type FieldError struct {
	Name              string
	TypeName          string
	Type              reflect.Type
	Message           string
	ParameterLocation string
	Parent            reflect.Type
}

FieldError is the error returned when an error related to a field occurs.

func (*FieldError) Error 

func (fe *FieldError) Error() string

Error implements the builtin error interface for FieldError.

type Generator 

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

Generator is an OpenAPI 3 generator.

func NewGenerator 

func NewGenerator(conf *SpecGenConfig) (*Generator, error)

NewGenerator returns a new OpenAPI generator.

func (*Generator) API 

func (g *Generator) API() *OpenAPI

API returns a copy of the internal OpenAPI object.

func (*Generator) AddOperation 

func (g *Generator) AddOperation(path, method, tag string, in, out reflect.Type, info *OperationInfo) (*Operation, error)

AddOperation add a new operation to the OpenAPI specification using the method and path of the route and the tonic handler informations.

func (*Generator) AddTag 

func (g *Generator) AddTag(name, desc string)

AddTag adds a new tag to the OpenAPI specification. If a tag already exists with the same name, it is overwritten.

func (*Generator) Errors 

func (g *Generator) Errors() []error

Errors returns the errors thar occurred during the generation of the specification.

func (*Generator) OverrideDataType 

func (g *Generator) OverrideDataType(t reflect.Type, typ, format string) error

OverrideDataType registers a custom schema type and format for the given type that will overrided the default generation.

func (*Generator) OverrideTypeName 

func (g *Generator) OverrideTypeName(t reflect.Type, name string) error

OverrideTypeName registers a custom name for a type that will override the default generation and have precedence over types that implements the Typer interface.

func (*Generator) SetAPIKeySecurity added in v0.13.7 

func (g *Generator) SetAPIKeySecurity(name string)

func (*Generator) SetInfo 

func (g *Generator) SetInfo(info *Info)

SetInfo uses the given OpenAPI info for the current specification.

func (*Generator) SetServers 

func (g *Generator) SetServers(servers []*Server)

SetServers sets the server list for the current specification.

func (*Generator) SetSortParams 

func (g *Generator) SetSortParams(b bool)

SetSortParams controls whether the generator should sort the parameters of an operation by location and name in ascending order.

func (*Generator) SetSortTags 

func (g *Generator) SetSortTags(b bool)

SetSortTags controls whether the generator should sort the global tags sections.

func (*Generator) UseFullSchemaNames 

func (g *Generator) UseFullSchemaNames(b bool)

UseFullSchemaNames defines whether the generator should generates a full name for the components using the package name of the type as a prefix. Omitting the package part of the name increases the risks of conflicts. It is the responsibility of the developper to ensure that unique type names are used across all the packages of the application. Default to true. 

type Header struct {
	Description     string       `json:"description,omitempty" yaml:"description,omitempty"`
	Required        bool         `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated      bool         `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmptyValue bool         `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Schema          *SchemaOrRef `json:"schema,omitempty" yaml:"schema,omitempty"`
}

Header represents an HTTP header.

type HeaderOrRef 

type HeaderOrRef struct {
	*Header
	*Reference
}

HeaderOrRef represents a Header that can be inlined or referenced in the API description.

func (*HeaderOrRef) MarshalYAML 

func (hor *HeaderOrRef) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for HeaderOrRef.

type Info 

type Info struct {
	Title          string   `json:"title" yaml:"title"`
	Description    string   `json:"description,omitempty" yaml:"description,omitempty"`
	TermsOfService string   `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
	Contact        *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
	License        *License `json:"license,omitempty" yaml:"license,omitempty"`
	Version        string   `json:"version" yaml:"version"`
}

Info represents the metadata of an API.

type InternalDataType 

type InternalDataType int

InternalDataType represents an internal type. 

const (
	TypeInteger InternalDataType = iota
	TypeLong
	TypeFloat
	TypeDouble
	TypeString
	TypeByte
	TypeBinary
	TypeBoolean
	TypeDate
	TypeDateTime
	TypeDuration
	TypeIP
	TypeURL
	TypePassword

	// TypeComplex represents non-primitive types like
	// Go struct, for which a schema must be generated.
	TypeComplex

	// Imported data types.
	TypeUUID

	TypeUnsupported
)

Type constants.

func (InternalDataType) Format 

func (dt InternalDataType) Format() string

Format returns the format corresponding to the DataType.

func (InternalDataType) String 

func (dt InternalDataType) String() string

String implements fmt.Stringer for DataType.

func (InternalDataType) Type 

func (dt InternalDataType) Type() string

Type returns the type corresponding to the DataType.

type License 

type License struct {
	Name string `json:"name" yaml:"name"`
	URL  string `json:"url,omitempty" yaml:"url,omitempty"`
}

License represents the license informations exposed for an API.

type MediaType 

type MediaType struct {
	Schema   *SchemaOrRef             `json:"schema" yaml:"schema"`
	Example  interface{}              `json:"example,omitempty" yaml:"example,omitempty"`
	Examples map[string]*ExampleOrRef `json:"examples,omitempty" yaml:"examples,omitempty"`
	Encoding map[string]*Encoding     `json:"encoding,omitempty" yaml:"encoding,omitempty"`
}

MediaType represents the type of a media.

type MediaTypeOrRef 

type MediaTypeOrRef struct {
	*MediaType
	*Reference
}

MediaTypeOrRef represents a MediaType that can be inlined or referenced in the API description.

func (*MediaTypeOrRef) MarshalYAML 

func (mtor *MediaTypeOrRef) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for MediaTypeOrRef.

type OpenAPI 

type OpenAPI struct {
	OpenAPI    string      `json:"openapi" yaml:"openapi"`
	Info       *Info       `json:"info" yaml:"info"`
	Servers    []*Server   `json:"servers,omitempty" yaml:"servers,omitempty"`
	Paths      Paths       `json:"paths" yaml:"paths"`
	Components *Components `json:"components,omitempty" yaml:"components,omitempty"`
	Tags       []*Tag      `json:"tags,omitempty" yaml:"tags,omitempty"`
}

OpenAPI represents the root document object of an OpenAPI document.

type Operation 

type Operation struct {
	Tags        []string                 `json:"tags,omitempty" yaml:"tags,omitempty"`
	Summary     string                   `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string                   `json:"description,omitempty" yaml:"description,omitempty"`
	ID          string                   `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Security    []map[string]interface{} `json:"security,omitempty" yaml:"security,omitempty"`
	Parameters  []*ParameterOrRef        `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody *RequestBody             `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Responses   Responses                `json:"responses,omitempty" yaml:"responses,omitempty"`
	Deprecated  bool                     `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	Servers     []*Server                `json:"servers,omitempty" yaml:"servers,omitempty"`
}

Operation describes an API operation on a path.

func (*Operation) GetDeprecated 

func (operation *Operation) GetDeprecated() bool

func (*Operation) GetDescription 

func (operation *Operation) GetDescription() string

func (*Operation) GetID 

func (operation *Operation) GetID() string

func (*Operation) GetParameters 

func (operation *Operation) GetParameters() []*ParameterOrRef

func (*Operation) GetRequestBody 

func (operation *Operation) GetRequestBody() *RequestBody

func (*Operation) GetResponses 

func (operation *Operation) GetResponses() Responses

func (*Operation) GetSecurity added in v0.13.10 

func (operation *Operation) GetSecurity() []map[string]interface{}

func (*Operation) GetServers 

func (operation *Operation) GetServers() []*Server

func (*Operation) GetSummary 

func (operation *Operation) GetSummary() string

func (*Operation) GetTags 

func (operation *Operation) GetTags() []string

func (*Operation) Marshal 

func (operation *Operation) Marshal() ([]byte, error)

func (*Operation) Unmarshal 

func (operation *Operation) Unmarshal(data []byte, v interface{}) error

type OperationInfo 

type OperationInfo struct {
	ID                string
	StatusCode        int
	StatusDescription string
	Headers           []*ResponseHeader
	Summary           string
	Description       string
	Deprecated        bool
	InputModel        interface{}
	Security          []map[string]interface{}
	Responses         []*OperationReponse
}

OperationInfo represents the informations of an operation that will be used when generating the OpenAPI specification.

type OperationReponse 

type OperationReponse struct {
	// The response code can be "default"
	// according to OAS3 spec.
	Code        string
	Description string
	Model       interface{}
	Headers     []*ResponseHeader
}

OperationReponse represents a single response of an API operation.

type OverridedDataType 

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

OverridedDataType represents a data type which details override the default generation.

func (*OverridedDataType) Format 

func (dt *OverridedDataType) Format() string

Format implements DataType for OverridedDataType.

func (*OverridedDataType) Type 

func (dt *OverridedDataType) Type() string

Type implements DataType for OverridedDataType.

type Parameter 

type Parameter struct {
	Name            string       `json:"name" yaml:"name"`
	In              string       `json:"in" yaml:"in"`
	Description     string       `json:"description,omitempty" yaml:"description,omitempty"`
	Required        bool         `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated      bool         `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmptyValue bool         `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Schema          *SchemaOrRef `json:"schema,omitempty" yaml:"schema,omitempty"`
	Style           string       `json:"style,omitempty" yaml:"style,omitempty"`
	Explode         bool         `json:"explode,omitempty" yaml:"explode,omitempty"`
}

Parameter describes a single operation parameter.

type ParameterOrRef 

type ParameterOrRef struct {
	*Parameter
	*Reference
}

ParameterOrRef represents a Parameter that can be inlined or referenced in the API description.

func (*ParameterOrRef) MarshalYAML 

func (por *ParameterOrRef) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for ParameterOrRef.

type PathItem 

type PathItem struct {
	Ref         string            `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Summary     string            `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string            `json:"description,omitempty" yaml:"description,omitempty"`
	GET         APIOperation      `json:"get,omitempty" yaml:"get,omitempty"`
	PUT         APIOperation      `json:"put,omitempty" yaml:"put,omitempty"`
	POST        APIOperation      `json:"post,omitempty" yaml:"post,omitempty"`
	DELETE      APIOperation      `json:"delete,omitempty" yaml:"delete,omitempty"`
	OPTIONS     APIOperation      `json:"options,omitempty" yaml:"options,omitempty"`
	HEAD        APIOperation      `json:"head,omitempty" yaml:"head,omitempty"`
	PATCH       APIOperation      `json:"patch,omitempty" yaml:"patch,omitempty"`
	TRACE       APIOperation      `json:"trace,omitempty" yaml:"trace,omitempty"`
	Servers     []*Server         `json:"servers,omitempty" yaml:"servers,omitempty"`
	Parameters  []*ParameterOrRef `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

PathItem describes the operations available on a single API path.

type Paths 

type Paths map[string]*PathItem

Paths represents the relative paths to the individual endpoints and their operations.

type Reference 

type Reference struct {
	Ref string `json:"$ref" yaml:"$ref"`
}

Reference is a simple object to allow referencing other components in the specification, internally and externally.

type RequestBody 

type RequestBody struct {
	Description string                `json:"description,omitempty" yaml:"description,omitempty"`
	Content     map[string]*MediaType `json:"content" yaml:"content"`
	Required    bool                  `json:"required,omitempty" yaml:"required,omitempty"`
}

RequestBody represents a request body.

type Response 

type Response struct {
	Description string                     `json:"description,omitempty" yaml:"description,omitempty"`
	Headers     map[string]*HeaderOrRef    `json:"headers,omitempty" yaml:"headers,omitempty"`
	Content     map[string]*MediaTypeOrRef `json:"content,omitempty" yaml:"content,omitempty"`
}

Response describes a single response from an API.

type ResponseHeader 

type ResponseHeader struct {
	Name        string
	Description string
	Model       interface{}
}

ResponseHeader represents a single header that may be returned with an operation response.

type ResponseOrRef 

type ResponseOrRef struct {
	*Response
	*Reference
}

ResponseOrRef represents a Response that can be inlined or referenced in the API description.

func (*ResponseOrRef) MarshalYAML 

func (ror *ResponseOrRef) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for ResponseOrRef.

type Responses 

type Responses map[string]*ResponseOrRef

Responses represents a container for the expected responses of an opration. It maps a HTTP response code to the expected response.

type Schema 

type Schema struct {
	// The following properties are taken from the JSON Schema
	// definition but their definitions were adjusted to the
	// OpenAPI Specification.
	Type                 string                  `json:"type,omitempty" yaml:"type,omitempty"`
	AllOf                *SchemaOrRef            `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	OneOf                *SchemaOrRef            `json:"oneOf,omitempty" yaml:"oneOf,omitempty"`
	AnyOf                *SchemaOrRef            `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`
	Items                *SchemaOrRef            `json:"items,omitempty" yaml:"items,omitempty"`
	Properties           map[string]*SchemaOrRef `json:"properties,omitempty" yaml:"properties,omitempty"`
	AdditionalProperties *SchemaOrRef            `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	Description          string                  `json:"description,omitempty" yaml:"description,omitempty"`
	Format               string                  `json:"format,omitempty" yaml:"format,omitempty"`
	Default              interface{}             `json:"default,omitempty" yaml:"default,omitempty"`

	// The following properties are taken directly from the
	// JSON Schema definition and follow the same specifications
	Title            string        `json:"title,omitempty" yaml:"title,omitempty"`
	MultipleOf       int           `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Maximum          int           `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum bool          `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum          int           `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	ExclusiveMinimum bool          `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	MaxLength        int           `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MinLength        int           `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty" yaml:"pattern,omitempty"`
	MaxItems         int           `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinItems         int           `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	UniqueItems      bool          `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	MaxProperties    int           `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	MinProperties    int           `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`
	Required         []string      `json:"required,omitempty" yaml:"required,omitempty"`
	Enum             []interface{} `json:"enum,omitempty" yaml:"enum,omitempty"`
	Nullable         bool          `json:"nullable,omitempty" yaml:"nullable,omitempty"`
	Deprecated       bool          `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
}

Schema represents the definition of input and output data types of the API.

type SchemaOrRef 

type SchemaOrRef struct {
	*Schema
	*Reference
}

SchemaOrRef represents a Schema that can be inlined or referenced in the API description.

func (*SchemaOrRef) MarshalYAML 

func (sor *SchemaOrRef) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for SchemaOrRef.

type Server 

type Server struct {
	URL         string                     `json:"url" yaml:"url"`
	Description string                     `json:"description,omitempty" yaml:"description,omitempty"`
	Variables   map[string]*ServerVariable `json:"variables,omitempty" yaml:"variables,omitempty"`
}

Server represents a server.

type ServerVariable 

type ServerVariable struct {
	Ennum       []string `json:"enum,omitempty" yaml:"enum,omitempty"`
	Default     string   `json:"default" yaml:"default"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
}

ServerVariable represents a server variable for server URL template substitution.

type SpecGenConfig 

type SpecGenConfig struct {
	// Name of the tag used by the validator.v8
	// package. This is used by the spec generator
	// to determine if a field is required.
	ValidatorTag      string
	PathLocationTag   string
	QueryLocationTag  string
	HeaderLocationTag string
	EnumTag           string
	DefaultTag        string
}

SpecGenConfig represents the configuration of the spec generator.

type Tag 

type Tag struct {
	Name        string `json:"name" yaml:"name"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Tag represents the metadata of a single tag.

type TypeError 

type TypeError struct {
	Message string
	Type    reflect.Type
}

TypeError is the error returned when the generator encounters an unknow or unsupported type.

func (*TypeError) Error 

func (te *TypeError) Error() string

Error implements the builtin error interface for TypeError.

type Typer 

type Typer interface {
	TypeName() string
}

Typer is the interface implemented by the types that can describe themselves.

Source Files

View all Source files

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.