openapiv2

Documentation

Overview

Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs.

Package openapiv2 produces OpenAPI Specification 2.0 (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) for the HTTP endpoints.

Index

• func Files(root *expr.RootExpr) ([]*codegen.File, error)
• type Header
• type Info
  • func (i Info) MarshalJSON() ([]byte, error)
  • func (i Info) MarshalYAML() (any, error)
• type Items
• type Operation
  • func (o Operation) MarshalJSON() ([]byte, error)
  • func (o Operation) MarshalYAML() (any, error)
• type Parameter
  • func (p Parameter) MarshalJSON() ([]byte, error)
  • func (p Parameter) MarshalYAML() (any, error)
• type Path
  • func (p Path) MarshalJSON() ([]byte, error)
  • func (p Path) MarshalYAML() (any, error)
• type Response
  • func (r Response) MarshalJSON() ([]byte, error)
  • func (r Response) MarshalYAML() (any, error)
• type Scope
• type SecurityDefinition
  • func (s SecurityDefinition) MarshalJSON() ([]byte, error)
  • func (s SecurityDefinition) MarshalYAML() (any, error)
• type V2
  • func NewV2(root *expr.RootExpr, h *expr.HostExpr) (*V2, error)

Functions

func Files

func Files(root *expr.RootExpr) ([]*codegen.File, error)

Files returns the OpenAPI v2 specification files in JSON and YAML formats.

Types

type Header

type Header struct {
	// Description is a brief description of the parameter.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	//  Type of the header. it is limited to simple types (that is, not an object).
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
	// Format is the extending format for the previously mentioned type.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
	// Items describes the type of items in the array if type is "array".
	Items *Items `json:"items,omitempty" yaml:"items,omitempty"`
	// CollectionFormat determines the format of the array if type array is used.
	// Possible values are csv, ssv, tsv, pipes and multi.
	CollectionFormat string `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"`
	// Default declares the value of the parameter that the server will use if none is
	// provided, for example a "count" to control the number of results per page might
	// default to 100 if not supplied by the client in the request.
	Default          any      `json:"default,omitempty" yaml:"default,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum bool     `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum          *float64 `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"`
	Enum             []any    `json:"enum,omitempty" yaml:"enum,omitempty"`
	MultipleOf       float64  `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
}

Header represents a header parameter.

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        *expr.ContactExpr `json:"contact,omitempty" yaml:"contact,omitempty"`
	License        *expr.LicenseExpr `json:"license,omitempty" yaml:"license,omitempty"`
	Version        string            `json:"version" yaml:"version"`
	Extensions     map[string]any    `json:"-" yaml:"-"`
}

Info provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the OpenAPI UI for convenience.

func (Info) MarshalJSON

func (i Info) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of i.

func (Info) MarshalYAML

func (i Info) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type Items

type Items struct {
	//  Type of the items. it is limited to simple types (that is, not an object).
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
	// Format is the extending format for the previously mentioned type.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
	// Items describes the type of items in the array if type is "array".
	Items *Items `json:"items,omitempty" yaml:"items,omitempty"`
	// CollectionFormat determines the format of the array if type array is used.
	// Possible values are csv, ssv, tsv, pipes and multi.
	CollectionFormat string `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"`
	// Default declares the value of the parameter that the server will use if none is
	// provided, for example a "count" to control the number of results per page might
	// default to 100 if not supplied by the client in the request.
	Default          any      `json:"default,omitempty" yaml:"default,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum bool     `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum          *float64 `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"`
	Enum             []any    `json:"enum,omitempty" yaml:"enum,omitempty"`
	MultipleOf       float64  `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
}

Items is a limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located in "body".

type Operation

type Operation struct {
	// Tags is a list of tags for API documentation control. Tags
	// can be used for logical grouping of operations by services or
	// any other qualifier.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Summary is a short summary of what the operation does. For maximum readability
	// in the swagger-ui, this field should be less than 120 characters.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// Description is a verbose explanation of the operation behavior.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// ExternalDocs points to additional external documentation for this operation.
	ExternalDocs *openapi.ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// OperationID is a unique string used to identify the operation.
	OperationID string `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	// Consumes is a list of MIME types the operation can consume.
	Consumes []string `json:"consumes,omitempty" yaml:"consumes,omitempty"`
	// Produces is a list of MIME types the operation can produce.
	Produces []string `json:"produces,omitempty" yaml:"produces,omitempty"`
	// Parameters is a list of parameters that are applicable for this operation.
	Parameters []*Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// Responses is the list of possible responses as they are returned from executing
	// this operation.
	Responses map[string]*Response `json:"responses,omitempty" yaml:"responses,omitempty"`
	// Schemes is the transfer protocol for the operation.
	Schemes []string `json:"schemes,omitempty" yaml:"schemes,omitempty"`
	// Deprecated declares this operation to be deprecated.
	Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	// Security is a declaration of which security schemes are applied for this operation.
	Security []map[string][]string `json:"security,omitempty" yaml:"security,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

Operation describes a single API operation on a path.

func (Operation) MarshalJSON

func (o Operation) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of o.

func (Operation) MarshalYAML

func (o Operation) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type Parameter

type Parameter struct {
	// Name of the parameter. Parameter names are case sensitive.
	Name string `json:"name" yaml:"name"`
	// In is the location of the parameter.
	// Possible values are "query", "header", "path", "formData" or "body".
	In string `json:"in" yaml:"in"`
	// Description is a brief description of the parameter.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Required determines whether this parameter is mandatory.
	Required bool `json:"required" yaml:"required"`
	// Schema defining the type used for the body parameter, only if "in" is body
	Schema *openapi.Schema `json:"schema,omitempty" yaml:"schema,omitempty"`

	//  Type of the parameter. Since the parameter is not located at the request body,
	// it is limited to simple types (that is, not an object).
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
	// Format is the extending format for the previously mentioned type.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
	// AllowEmptyValue sets the ability to pass empty-valued parameters.
	// This is valid only for either query or formData parameters and allows you to
	// send a parameter with a name only or an empty value. Default value is false.
	AllowEmptyValue bool `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	// Items describes the type of items in the array if type is "array".
	Items *Items `json:"items,omitempty" yaml:"items,omitempty"`
	// CollectionFormat determines the format of the array if type array is used.
	// Possible values are csv, ssv, tsv, pipes and multi.
	CollectionFormat string `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"`
	// Default declares the value of the parameter that the server will use if none is
	// provided, for example a "count" to control the number of results per page might
	// default to 100 if not supplied by the client in the request.
	Default          any      `json:"default,omitempty" yaml:"default,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum bool     `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum          *float64 `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"`
	Enum             []any    `json:"enum,omitempty" yaml:"enum,omitempty"`
	MultipleOf       float64  `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

Parameter describes a single operation parameter.

func (Parameter) MarshalJSON

func (p Parameter) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of p.

func (Parameter) MarshalYAML

func (p Parameter) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type Path

type Path struct {
	// Ref allows for an external definition of this path item.
	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	// Get defines a GET operation on this path.
	Get *Operation `json:"get,omitempty" yaml:"get,omitempty"`
	// Put defines a PUT operation on this path.
	Put *Operation `json:"put,omitempty" yaml:"put,omitempty"`
	// Post defines a POST operation on this path.
	Post *Operation `json:"post,omitempty" yaml:"post,omitempty"`
	// Delete defines a DELETE operation on this path.
	Delete *Operation `json:"delete,omitempty" yaml:"delete,omitempty"`
	// Options defines a OPTIONS operation on this path.
	Options *Operation `json:"options,omitempty" yaml:"options,omitempty"`
	// Head defines a HEAD operation on this path.
	Head *Operation `json:"head,omitempty" yaml:"head,omitempty"`
	// Patch defines a PATCH operation on this path.
	Patch *Operation `json:"patch,omitempty" yaml:"patch,omitempty"`
	// Parameters is the list of parameters that are applicable for all the operations
	// described under this path.
	Parameters []*Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

Path holds the relative paths to the individual endpoints.

func (Path) MarshalJSON

func (p Path) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of p.

func (Path) MarshalYAML

func (p Path) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type Response

type Response struct {
	// Description of the response. GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Schema is a definition of the response structure. It can be a primitive,
	// an array or an object. If this field does not exist, it means no content is
	// returned as part of the response. As an extension to the Schema Object, its root
	// type value may also be "file".
	Schema *openapi.Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
	// Headers is a list of headers that are sent with the response.
	Headers map[string]*Header `json:"headers,omitempty" yaml:"headers,omitempty"`
	// Ref references a global API response.
	// This field is exclusive with the other fields of Response.
	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

Response describes an operation response.

func (Response) MarshalJSON

func (r Response) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of r.

func (Response) MarshalYAML

func (r Response) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type Scope

type Scope struct {
	// Description for scope
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Scope corresponds to an available scope for an OAuth2 security scheme.

type SecurityDefinition

type SecurityDefinition struct {
	// Type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
	Type string `json:"type" yaml:"type"`
	// Description for security scheme
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Name of the header or query parameter to be used when type is "apiKey".
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// In is the location of the API key when type is "apiKey".
	// Valid values are "query" or "header".
	In string `json:"in,omitempty" yaml:"in,omitempty"`
	// Flow is the flow used by the OAuth2 security scheme when type is "oauth2"
	// Valid values are "implicit", "password", "application" or "accessCode".
	Flow string `json:"flow,omitempty" yaml:"flow,omitempty"`
	// The oauth2 authorization URL to be used for this flow.
	AuthorizationURL string `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
	// TokenURL  is the token URL to be used for this flow.
	TokenURL string `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
	// Scopes list the  available scopes for the OAuth2 security scheme.
	Scopes map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

SecurityDefinition allows the definition of a security scheme that can be used by the operations. Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code).

func (SecurityDefinition) MarshalJSON

func (s SecurityDefinition) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of s.

func (SecurityDefinition) MarshalYAML

func (s SecurityDefinition) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type V2

type V2 struct {
	Swagger             string                         `json:"swagger,omitempty" yaml:"swagger,omitempty"`
	Info                *Info                          `json:"info,omitempty" yaml:"info,omitempty"`
	Host                string                         `json:"host,omitempty" yaml:"host,omitempty"`
	BasePath            string                         `json:"basePath,omitempty" yaml:"basePath,omitempty"`
	Schemes             []string                       `json:"schemes,omitempty" yaml:"schemes,omitempty"`
	Consumes            []string                       `json:"consumes,omitempty" yaml:"consumes,omitempty"`
	Produces            []string                       `json:"produces,omitempty" yaml:"produces,omitempty"`
	Paths               map[string]any                 `json:"paths" yaml:"paths"`
	Definitions         map[string]*openapi.Schema     `json:"definitions,omitempty" yaml:"definitions,omitempty"`
	Parameters          map[string]*Parameter          `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Responses           map[string]*Response           `json:"responses,omitempty" yaml:"responses,omitempty"`
	SecurityDefinitions map[string]*SecurityDefinition `json:"securityDefinitions,omitempty" yaml:"securityDefinitions,omitempty"`
	Tags                []*openapi.Tag                 `json:"tags,omitempty" yaml:"tags,omitempty"`
	ExternalDocs        *openapi.ExternalDocs          `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
}

V2 represents an instance of a Swagger object. See https://github.com/OAI/OpenAPI-Specification

func NewV2

func NewV2(root *expr.RootExpr, h *expr.HostExpr) (*V2, error)

NewV2 returns the OpenAPI v2 specification for the given API.