openapi

package module
v0.0.0-...-c62c58b Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2024 License: MIT Imports: 14 Imported by: 21

README

OpenAPI Specification object model

GoDoc Build Status codecov

This package is still under development, so the API will be changed without any notification

Overview

This is an implementation of OpenAPI Specification 3.0 object model with some usable functions.

Synopsis

package main

import (
    "fmt"

    "github.com/nasa9084/go-openapi"
)

func main() {
    doc, _ := openapi.LoadFile("path/to/spec")
    fmt.Print(doc.Version)
}

Status

  • Model definition
  • Load OpenAPI 3.0 spec file
  • Resolve Reference object
    • Resolve #/component reference
    • Resolve other file reference
  • Validation
    • Validate spec values
      • test for validation
        • Document
        • Info
        • Contact
        • License
        • Server
        • ServerVariable
        • Paths
        • PathItem
        • Operation
        • Parameter
        • RequestBody
        • Responses
        • Response
        • Callbacks
        • Callback
        • Schema
        • Example
        • MediaType
        • Header
        • Link
        • Encoding
        • Discriminator
        • XML
        • Components
        • SecurityScheme
        • OAuthFlows
        • OAuthFlow
        • SecurityRequirement
        • Tag
        • ExternalDocumentation
    • Validate HTTP Request
    • Validate HTTP Response

Documentation

Index

Constants

View Source 
const (
	// ErrUnsupportedVersion is returned when the openapi version
	// is unsupported by this package.
	ErrUnsupportedVersion errString = "the OAS version is not supported"
	// ErrInvalidFlowType is returned when the OAuth flow type is invalid
	// or not set to the object.
	ErrInvalidFlowType errString = "invalid flow type"
	// ErrRequiredMustTrue is returned when the value of parameter.required is
	// false when parameter.in is path.
	ErrRequiredMustTrue errString = "required must be true if parameter.in is path"
	// ErrAllowEmptyValueNotValid is returned when allowEmptyValue is specified
	// but parameter.in is not query.
	ErrAllowEmptyValueNotValid errString = "allowEmptyValue is valid only for query parameters"
	// ErrInvalidStatusCode is returned when specified status code is not
	// valid as HTTP status code.
	ErrInvalidStatusCode errString = "status code is invalid"
	// ErrMissingRootDocument is returned when validating securityRequirement
	// object but root document is not set.
	ErrMissingRootDocument errString = "missing root document for security requirement"
)

Variables

View Source 
var (
	ErrMapKeyFormat      = ErrFormatInvalid{Target: "map key"}
	ErrPathFormat        = ErrFormatInvalid{Target: "path"}
	ErrRuntimeExprFormat = ErrFormatInvalid{Target: "key", Format: "RuntimeExpression"}
)

central error variables relating format

View Source 
var (
	// ErrTooManyHeaderContent is returned when the length of header.content
	// is more than 2.
	ErrTooManyHeaderContent = errTooManyContentEntry{/* contains filtered or unexported fields */}
	// ErrTooManyParameterContent is returned when the length of parameter.content
	// is more than 2.
	ErrTooManyParameterContent = errTooManyContentEntry{/* contains filtered or unexported fields */}
)
View Source 
var (
	// ErrOperationIDDuplicated is returned when some operation ids are
	// duplicated but operation ids cannot be duplicated.
	ErrOperationIDDuplicated = errDuplicated{/* contains filtered or unexported fields */}
	// ErrParameterDuplicated is returned when some parameters are duplicated
	// but cannot be duplicated.
	ErrParameterDuplicated = errDuplicated{/* contains filtered or unexported fields */}
	// ErrPathsDuplicated is returned when some paths are duplicated.
	ErrPathsDuplicated = errDuplicated{/* contains filtered or unexported fields */}
)
View Source 
var (
	ParameterInList      = []string{string(InQuery), string(InHeader), string(InPath), string(InCookie)}
	SecuritySchemeInList = []string{string(InQuery), string(InHeader), string(InCookie)}
)

InType Lists for ErrOneOf

View Source 
var ErrTypeAssertion = errors.New("type assertion error")

ErrTypeAssertion is raised when the type assertion error is occurred.

View Source 
var SecuritySchemeTypeList = []string{string(APIKeyType), string(HTTPType), string(OAuth2Type), string(OpenIDConnectType)}

SecuritySchemeTypeList is a list of valid values of securityScheme.Type.

Functions

This section is empty.

Types

type Callback 

type Callback map[string]*PathItem

Callback Object

func ResolveCallback 

func ResolveCallback(root *Document, ref string) (*Callback, error)

ResolveCallback resolves a callback reference string.

func (Callback) Validate 

func (callback Callback) Validate() error

Validate the values of Callback object.

type Components 

type Components struct {
	Schemas         map[string]*Schema
	Responses       map[string]*Response
	Parameters      map[string]*Parameter
	Examples        map[string]*Example
	RequestBodies   map[string]*RequestBody `yaml:"requestBodies"`
	Headers         map[string]*Header
	SecuritySchemes map[string]*SecurityScheme `yaml:"securitySchemes"`
	Links           map[string]*Link
	Callbacks       map[string]*Callback
}

Components Object

func (Components) Validate 

func (components Components) Validate() error

Validate the values of Components object.

type Contact 

type Contact struct {
	Name  string
	URL   string
	Email string
}

Contact Object

func (Contact) Validate 

func (contact Contact) Validate() error

Validate the values of Contact object.

type Discriminator 

type Discriminator struct {
	PropertyName string `yaml:"propertyName"`
	Mapping      map[string]string
}

Discriminator Object

func (Discriminator) Validate 

func (discriminator Discriminator) Validate() error

Validate the values of Descriminator object.

type Document 

type Document struct {
	Version      string `yaml:"openapi"`
	Info         *Info
	Servers      []*Server
	Paths        Paths
	Components   *Components
	Security     []*SecurityRequirement
	Tags         []*Tag
	ExternalDocs *ExternalDocumentation `yaml:"externalDocs"`
}

Document represents a OpenAPI Specification document.

func Load 

func Load(b []byte) (*Document, error)

Load OpenAPI Specification v3.0 spec.

func LoadFile 

func LoadFile(filename string) (*Document, error)

LoadFile OpenAPI Specification v3.0 spec file.

func (Document) Validate 

func (doc Document) Validate() error

Validate the values of spec.

func (*Document) Walk 

func (doc *Document) Walk(walkFn WalkFunc) error

type Encoding 

type Encoding struct {
	ContentType   string `yaml:"contentType"`
	Headers       map[string]*Header
	Style         string
	Explode       bool
	AllowReserved bool `yaml:"allowReserved"`
}

Encoding Object

func (Encoding) Validate 

func (encoding Encoding) Validate() error

Validate the values of Encoding object.

type ErrFormatInvalid 

type ErrFormatInvalid struct {
	Target string
	Format string
}

ErrFormatInvalid is returned some error caused by string format is occurred.

func (ErrFormatInvalid) Error 

func (fe ErrFormatInvalid) Error() string

type ErrMustEmpty 

type ErrMustEmpty struct {
	Type string
}

ErrMustEmpty returned when the securityRequirement is not empty but must be empty.

func (ErrMustEmpty) Error 

func (srmee ErrMustEmpty) Error() string

type ErrMustOneOf 

type ErrMustOneOf struct {
	Object      string
	ValidValues []string
}

ErrMustOneOf is returned some value must be one of given list, but not one.

func (ErrMustOneOf) Error 

func (ooe ErrMustOneOf) Error() string

type ErrNotDeclared 

type ErrNotDeclared struct {
	Name string
}

ErrNotDeclared is returned when the securityScheme name is not defined in components object in the document.

func (ErrNotDeclared) Error 

func (snde ErrNotDeclared) Error() string

type ErrRequired 

type ErrRequired struct {
	Target string
}

ErrRequired is returned when missing some required parameter

func (ErrRequired) Error 

func (re ErrRequired) Error() string

type Example 

type Example struct {
	Summary       string
	Description   string
	Value         interface{}
	ExternalValue interface{} `yaml:"externalValue"`

	Ref string `yaml:"$ref"`
}

Example Object

func ResolveExample 

func ResolveExample(root *Document, ref string) (*Example, error)

ResolveExample resolves an example reference string.

type ExternalDocumentation 

type ExternalDocumentation struct {
	Description string
	URL         string
}

ExternalDocumentation Object

func (ExternalDocumentation) Validate 

func (externalDocumentation ExternalDocumentation) Validate() error

Validate the values of ExternalDocumentaion object. 

type Header struct {
	Description     string
	Required        bool
	Deprecated      string
	AllowEmptyValue bool `yaml:"allowEmptyValue"`

	Style         string
	Explode       bool
	AllowReserved bool `yaml:"allowReserved"`
	Schema        *Schema
	Example       interface{}
	Examples      map[string]*Example

	Content map[string]*MediaType

	Ref string `yaml:"$ref"`
}

Header Object

func ResolveHeader 

func ResolveHeader(root *Document, ref string) (*Header, error)

ResolveHeader resolves a header reference string.

func (Header) Validate 

func (header Header) Validate() error

Validate the values of Header object.

type InType 

type InType string

InType represents where the parameter or the securityScheme is in. 

const (
	InQuery  InType = "query"
	InHeader InType = "header"
	InPath   InType = "path"
	InCookie InType = "cookie"
)

InTypes

type Info 

type Info struct {
	Title          string
	Description    string
	TermsOfService string `yaml:"termsOfService"`
	Contact        *Contact
	License        *License
	Version        string
}

Info Object

func (Info) Validate 

func (info Info) Validate() error

Validate the values of Info object.

type License 

type License struct {
	Name string
	URL  string
}

License Object

func (License) Validate 

func (license License) Validate() error

Validate the values of License object. 

type Link struct {
	OperationRef string `yaml:"operationRef"`
	OperationID  string `yaml:"operationId"`
	Parameters   map[string]interface{}
	RequestBody  interface{} `yaml:"requestBody"`
	Description  string
	Server       *Server

	Ref string `yaml:"$ref"`
}

Link Object 

func ResolveLink(root *Document, ref string) (*Link, error)

ResolveLink resolves a link reference string.

func (Link) Validate 

func (link Link) Validate() error

Validate the values of Link object.

type MediaType 

type MediaType struct {
	Schema   *Schema
	Example  interface{}
	Examples map[string]*Example
	Encoding map[string]*Encoding
}

MediaType Object

func (MediaType) Validate 

func (mediaType MediaType) Validate() error

Validate the values of MediaType object. This function DOES NOT check whether the encoding object is in schema or not.

type OAuthFlow 

type OAuthFlow struct {
	AuthorizationURL string `yaml:"authorizationUrl"`
	TokenURL         string `yaml:"tokenUrl"`
	RefreshURL       string `yaml:"refreshUrl"`
	Scopes           map[string]string
	// contains filtered or unexported fields
}

OAuthFlow Object

func (*OAuthFlow) SetFlowType 

func (oauthFlow *OAuthFlow) SetFlowType(typ string)

SetFlowType sets oauth flow type.

func (OAuthFlow) Validate 

func (oauthFlow OAuthFlow) Validate() error

Validate the values of OAuthFlow object.

type OAuthFlows 

type OAuthFlows struct {
	Implicit          *OAuthFlow
	Password          *OAuthFlow
	ClientCredentials *OAuthFlow `yaml:"clientCredentials"`
	AuthorizationCode *OAuthFlow `yaml:"authorizationCode"`
}

OAuthFlows Object

func (OAuthFlows) Validate 

func (oauthFlows OAuthFlows) Validate() error

Validate the values of OAuthFlows Object.

type Operation 

type Operation struct {
	Tags         []string
	Summary      string
	Description  string
	ExternalDocs *ExternalDocumentation `yaml:"externalDocs"`
	OperationID  string                 `yaml:"operationId"`
	Parameters   []*Parameter
	RequestBody  *RequestBody `yaml:"requestBody"`
	Responses    Responses
	Callbacks    map[string]*Callback
	Deprecated   bool
	Security     []*SecurityRequirement
	Servers      []*Server
}

Operation Object

func (*Operation) SuccessResponse 

func (operation *Operation) SuccessResponse() (*Response, int, bool)

SuccessResponse returns a success response object. If there are 2 or more success responses (like created and ok), it's not sure which is returned. If only match the default response or 2XX response, returned status code will be 0.

func (Operation) Validate 

func (operation Operation) Validate() error

Validate the values of Operation object.

type Parameter 

type Parameter struct {
	Name            string
	In              InType
	Description     string
	Required        bool
	Deprecated      string
	AllowEmptyValue bool `yaml:"allowEmptyValue"`

	Style         string
	Explode       bool
	AllowReserved bool `yaml:"allowReserved"`
	Schema        *Schema
	Example       interface{}
	Examples      map[string]*Example

	Content map[string]*MediaType

	Ref string `yaml:"$ref"`
}

Parameter Object

func ResolveParameter 

func ResolveParameter(root *Document, ref string) (*Parameter, error)

ResolveParameter resolves a response reference string.

func (Parameter) Validate 

func (parameter Parameter) Validate() error

Validate the values of Parameter object. This function DOES NOT check whether the name field correspond to the associated path or not.

type PathItem 

type PathItem struct {
	Ref string `yaml:"$ref"`

	Summary     string
	Description string
	Get         *Operation
	Put         *Operation
	Post        *Operation
	Delete      *Operation
	Options     *Operation
	Head        *Operation
	Patch       *Operation
	Trace       *Operation
	Servers     []*Server
	Parameters  []*Parameter
}

PathItem Object

func (PathItem) GetOperationByID 

func (pathItem PathItem) GetOperationByID(operationID string) *Operation

GetOperationByID returns an operation object which matches given operationId. If the pathItem object has duplicated operationId, this function returns one which match first.

func (*PathItem) GetOperationByMethod 

func (pathItem *PathItem) GetOperationByMethod(method string) *Operation

GetOperationByMethod returns a operation object associated with given method. The method is case-insensitive, converted to upper case in this function. If the method is invalid, this function will return nil.

func (PathItem) Operations 

func (pathItem PathItem) Operations() map[string]*Operation

Operations returns a map containing operation object as a value associated with a HTTP method as a key. If an operation is nil, it won't be added returned map, so the size of returned map is not same always.

func (PathItem) Validate 

func (pathItem PathItem) Validate() error

Validate the values of PathItem object.

type Paths 

type Paths map[string]*PathItem

Paths Object

func (Paths) GetOperationByID 

func (paths Paths) GetOperationByID(operationID string) *Operation

GetOperationByID returns an operation by operationId. If the paths object has two or more operations which matches given operationId, this function returns the operation matched first. So you should call Validate() before using this function.

func (Paths) Validate 

func (paths Paths) Validate() error

Validate the values of Paths object.

type RequestBody 

type RequestBody struct {
	Description string
	Content     map[string]*MediaType
	Required    bool

	Ref string `yaml:"$ref"`
}

RequestBody Object

func ResolveRequestBody 

func ResolveRequestBody(root *Document, ref string) (*RequestBody, error)

ResolveRequestBody resolves a requestBody reference string.

func (RequestBody) Validate 

func (requestBody RequestBody) Validate() error

Validate the values of RequestBody object.

type Response 

type Response struct {
	Description string
	Headers     map[string]*Header
	Content     map[string]*MediaType
	Links       map[string]*Link

	Ref string `yaml:"$ref"`
}

Response Object

func ResolveResponse 

func ResolveResponse(root *Document, ref string) (*Response, error)

ResolveResponse resolves a response reference string.

func (Response) Validate 

func (response Response) Validate() error

Validate the value of Response object.

type Responses 

type Responses map[string]*Response

Responses Object

func (Responses) Validate 

func (responses Responses) Validate() error

Validate the values of Responses object.

type Schema 

type Schema struct {
	Title            string
	MultipleOf       int `yaml:"multipleOf"`
	Maximum          int
	ExclusiveMaximum bool `yaml:"exclusiveMaximum"`
	Minimum          int
	ExclusiveMinimum bool `yaml:"exclusiveMinimum"`
	MaxLength        int  `yaml:"maxLength"`
	MinLength        int  `yaml:"minLength"`
	Pattern          string
	MaxItems         int `yaml:"maxItems"`
	MinItems         int `yaml:"minItems"`
	MaxProperties    int `yaml:"maxProperties"`
	MinProperties    int `yaml:"minProperties"`
	Required         []string
	Enum             []string

	Type                 string
	AllOf                []*Schema `yaml:"allOf"`
	OneOf                []*Schema `yaml:"oneOf"`
	AnyOf                []*Schema `yaml:"anyOf"`
	Not                  *Schema
	Items                *Schema
	Properties           map[string]*Schema
	AdditionalProperties *Schema `yaml:"additionalProperties"`
	Description          string
	Format               string
	Default              interface{}

	Nullable      bool
	Discriminator *Discriminator
	ReadOnly      bool `yaml:"readOnly"`
	WriteOnly     bool `yaml:"writeOnly"`
	XML           *XML
	ExternalDocs  *ExternalDocumentation `yaml:"externalDocs"`
	Example       interface{}
	Deprecated    bool

	Ref string `yaml:"$ref"`

	Extension map[string]interface{} `yaml:",inline"`
}

Schema Object

func ResolveSchema 

func ResolveSchema(root *Document, ref string) (*Schema, error)

ResolveSchema resolves a schema reference string.

func (Schema) Validate 

func (schema Schema) Validate() error

Validate the values of Schema object.

type SecurityRequirement 

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

SecurityRequirement Object

func (SecurityRequirement) Get 

func (secReq SecurityRequirement) Get(name string) []string

Get returns required security schemes. If there is not given name, this function returns nil.

func (SecurityRequirement) Names 

func (secReq SecurityRequirement) Names() []string

Names returns the keys of security requirements. The returned slice is sorted.

func (*SecurityRequirement) UnmarshalJSON 

func (secReq *SecurityRequirement) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*SecurityRequirement) UnmarshalYAML 

func (secReq *SecurityRequirement) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler.

func (SecurityRequirement) Validate 

func (secReq SecurityRequirement) Validate() error

Validate the values of SecurityRequirement object.

type SecurityScheme 

type SecurityScheme struct {
	Type             SecuritySchemeType
	Description      string
	Name             string
	In               InType
	Scheme           string
	BearerFormat     string `yaml:"bearerFormat"`
	Flows            *OAuthFlows
	OpenIDConnectURL string `yaml:"openIdConnectUrl"`

	Ref string `yaml:"$ref"`
}

SecurityScheme Object

func ResolveSecurityScheme 

func ResolveSecurityScheme(root *Document, ref string) (*SecurityScheme, error)

ResolveSecurityScheme resolves a securityScheme reference string.

func (SecurityScheme) Validate 

func (secScheme SecurityScheme) Validate() error

Validate the values of SecurityScheme object.

type SecuritySchemeType 

type SecuritySchemeType string

SecuritySchemeType represents a securityScheme.type value. 

const (
	APIKeyType        SecuritySchemeType = "apiKey"
	HTTPType          SecuritySchemeType = "http"
	OAuth2Type        SecuritySchemeType = "oauth2"
	OpenIDConnectType SecuritySchemeType = "openIdConnect"
)

SecuritySchemeTypes

type Server 

type Server struct {
	URL         string
	Description string
	Variables   map[string]*ServerVariable
}

Server Object

func (Server) Validate 

func (server Server) Validate() error

Validate the values of Server object.

type ServerVariable 

type ServerVariable struct {
	Enum        []string
	Default     string
	Description string
}

ServerVariable Object

func (ServerVariable) Validate 

func (sv ServerVariable) Validate() error

Validate the values of Server Variable object.

type Tag 

type Tag struct {
	Name         string
	Description  string
	ExternalDocs *ExternalDocumentation `yaml:"externalDocs"`
}

Tag Object

func (Tag) Validate 

func (tag Tag) Validate() error

Validate the values of Tag object.

type WalkFunc 

type WalkFunc func(doc *Document, method, path string, pathItem *PathItem, op *Operation) error

type XML 

type XML struct {
	Name      string
	Namespace string
	Prefix    string
	Attribute bool
	Wrapped   bool
}

XML Object

func (XML) Validate 

func (xml XML) Validate() error

Validate the values of XML object.

Source Files

View all Source files

Directories

Path Synopsis

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.