openapi

Documentation

Index

• Constants
• Variables
• func CreateCURLBody(content any, contentType string) (string, error)
• func EncodeContent(content any, contentType string) ([]byte, error)
• func FixSchemaTypeTypos(typ string) string
• func GetOpenAPITypeFromValue(value any) string
• func TransformHTTPCode(httpCode string) int
• type AuthLocation
• type AuthScheme
• type AuthType
• type ContentExample
• type Document
• type GenerateRequestOptions
• type GeneratedRequest
• type GeneratedResponse
• type Headers
• type Operation
• type OperationDescription
• type Parameter
• type Parameters
• type Request
• type RequestBody
• type Response
• type Schema
• type SecurityComponent
• type SecurityComponents
• type Validator

Constants

const (
	TypeArray   = "array"
	TypeBoolean = "boolean"
	TypeInteger = "integer"
	TypeNumber  = "number"
	TypeObject  = "object"
	TypeString  = "string"
)

const (
	ParameterInPath   = "path"
	ParameterInQuery  = "query"
	ParameterInHeader = "header"
	// ParameterInBody v2 Swagger only
	ParameterInBody = "body"
)

Variables

var (
	ErrUnexpectedFormDataType       = errors.New("expected map[string]any for multipart/form-data")
	ErrUnexpectedFormURLEncodedType = errors.New("expected map[string]any for x-www-form-urlencoded")
)

Functions

func CreateCURLBody

func CreateCURLBody(content any, contentType string) (string, error)

func EncodeContent

func EncodeContent(content any, contentType string) ([]byte, error)

EncodeContent encodes content to the given content type. Since it is part of the JSON GeneratedRequest, we need to encode different content types to string before sending it.

func FixSchemaTypeTypos

func FixSchemaTypeTypos(typ string) string

FixSchemaTypeTypos fixes common typos in schema types.

func GetOpenAPITypeFromValue

func GetOpenAPITypeFromValue(value any) string

func TransformHTTPCode

func TransformHTTPCode(httpCode string) int

TransformHTTPCode transforms HTTP code from the OpenAPI spec to the real HTTP code.

Types

type AuthLocation

type AuthLocation string

const (
	AuthLocationHeader AuthLocation = "header"
	AuthLocationQuery  AuthLocation = "query"
)

type AuthScheme

type AuthScheme string

const (
	AuthSchemeBearer AuthScheme = "bearer"
	AuthSchemeBasic  AuthScheme = "basic"
)

type AuthType

type AuthType string

const (
	AuthTypeHTTP   AuthType = "http"
	AuthTypeApiKey AuthType = "apiKey"
)

type ContentExample

type ContentExample struct {
	CURL string `json:"curl,omitempty"`
}

ContentExample is a struct that represents a generated cURL example.

type Document

type Document interface {
	Provider() config.SchemaProvider
	GetVersion() string
	GetResources() map[string][]string
	GetSecurity() SecurityComponents
	FindOperation(options *OperationDescription) Operation
}

Document is an interface that represents an OpenAPI document needed for content generation. It is implemented by the LibV2Document and LibV3Document types.

type GenerateRequestOptions

type GenerateRequestOptions struct {
	PathPrefix string
	Path       string
	Method     string
	Operation  Operation
}

type GeneratedRequest

type GeneratedRequest struct {
	Headers       map[string]any  `json:"headers,omitempty"`
	Method        string          `json:"method,omitempty"`
	Path          string          `json:"path,omitempty"`
	Query         string          `json:"query,omitempty"`
	Body          string          `json:"body,omitempty"`
	ContentType   string          `json:"contentType,omitempty"`
	ContentSchema *Schema         `json:"contentSchema,omitempty"`
	Examples      *ContentExample `json:"examples,omitempty"`

	// internal fields. needed for some validation providers.
	Operation Operation     `json:"-"`
	Request   *http.Request `json:"-"`
}

GeneratedRequest is a struct that represents a generated GeneratedRequest to be used when building real endpoint GeneratedRequest.

type GeneratedResponse

type GeneratedResponse struct {
	Headers     http.Header `json:"headers,omitempty"`
	Content     []byte      `json:"content,omitempty"`
	ContentType string      `json:"contentType,omitempty"`
	StatusCode  int         `json:"statusCode,omitempty"`

	// internal fields. needed for some validation providers.
	Operation Operation     `json:"-"`
	Request   *http.Request `json:"-"`
}

GeneratedResponse is a struct that represents a generated response to be used when comparing real endpoint response.

type Headers

type Headers map[string]*Parameter

Headers is a map of Parameter.

type Operation

type Operation interface {
	ID() string
	GetRequest(securityComponents SecurityComponents) *Request
	GetResponse() *Response
	WithParseConfig(*config.ParseConfig) Operation
}

Operation is an interface that represents an OpenAPI operation needed for content generation.

type OperationDescription

type OperationDescription struct {
	Service  string
	Resource string
	Method   string
}

OperationDescription is a struct that used to find an operation in an OpenAPI document.

type Parameter

type Parameter struct {
	Name     string  `json:"name,omitempty" yaml:"name,omitempty"`
	In       string  `json:"in,omitempty" yaml:"in,omitempty"`
	Required bool    `json:"required,omitempty" yaml:"required,omitempty"`
	Schema   *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example  any     `json:"example,omitempty" yaml:"example,omitempty"`
}

Parameter is a struct that represents an OpenAPI parameter.

type Parameters

type Parameters []*Parameter

Parameters is a slice of Parameter.

type Request

type Request struct {
	Parameters Parameters
	Body       *RequestBody
}

type RequestBody

type RequestBody struct {
	Schema *Schema
	Type   string
}

type Response

type Response struct {
	Headers     Headers
	Content     *Schema
	ContentType string
	StatusCode  int
}

Response is a struct that represents an OpenAPI response.

type Schema

type Schema struct {
	Type string `json:"type,omitempty" yaml:"type,omitempty"`

	// in 3.1 examples can be an array (which is recommended)
	Examples []any `json:"examples,omitempty" yaml:"examples,omitempty"`

	// items can be a schema in 2.0, 3.0 and 3.1 or a bool in 3.1
	Items *Schema `json:"items,omitempty" yaml:"items,omitempty"`

	// Compatible with all versions
	MultipleOf    float64            `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Maximum       float64            `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	Minimum       float64            `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	MaxLength     int64              `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MinLength     int64              `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	Pattern       string             `json:"pattern,omitempty" yaml:"pattern,omitempty"`
	Format        string             `json:"format,omitempty" yaml:"format,omitempty"`
	MaxItems      int64              `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinItems      int64              `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	MaxProperties int64              `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	MinProperties int64              `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`
	Required      []string           `json:"required,omitempty" yaml:"required,omitempty"`
	Enum          []any              `json:"enum,omitempty" yaml:"enum,omitempty"`
	Properties    map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
	Not           *Schema            `json:"not,omitempty" yaml:"not,omitempty"`
	Default       any                `json:"default,omitempty" yaml:"default,omitempty"`
	Nullable      bool               `json:"nullable,omitempty" yaml:"nullable,omitempty"`
	ReadOnly      bool               `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	WriteOnly     bool               `json:"writeOnly,omitempty" yaml:"writeOnly,omitempty"`
	Example       any                `json:"example,omitempty" yaml:"example,omitempty"`
	Deprecated    bool               `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
}

Schema is a struct that represents an OpenAPI schema. It is compatible with all versions of OpenAPI. All schema providers should implement the Document and Operation interfaces. This provides a unified way to work with different OpenAPI parsers.

type SecurityComponent

type SecurityComponent struct {
	Type   AuthType
	Scheme AuthScheme
	In     AuthLocation
	Name   string
}

type SecurityComponents

type SecurityComponents map[string]*SecurityComponent

type Validator

type Validator interface {
	ValidateRequest(req *GeneratedRequest) []error
	ValidateResponse(res *GeneratedResponse) []error
}

Validator is an interface that represents an OpenAPI validator.