openapi

Documentation

Overview

Package openapi contains tools to read in OpenAPI specifications so that they can be passed to the openapi2proto compiler

Index

• type Endpoint
• type Extension
• type ExtensionField
• type GlobalOptions
• type Model
• type Option
  • func WithDir(s string) Option
• type Parameter
• type Parameters
• type Path
• type Response
• type Schema
  • func (s Schema) IsNil() bool
  • func (s *Schema) UnmarshalJSON(data []byte) error
• type SchemaType
  • func (s *SchemaType) Contains(t string) bool
  • func (s *SchemaType) Empty() bool
  • func (s *SchemaType) First() string
  • func (s *SchemaType) Len() int
  • func (s *SchemaType) UnmarshalJSON(data []byte) error
  • func (s *SchemaType) UnmarshalYAML(unmarshal func(interface{}) error) error
• type Spec
  • func LoadFile(fn string) (*Spec, error)

Types

type Endpoint

type Endpoint struct {
	Path          string                 `yaml:"-" json:"-"` // this is added internally
	Verb          string                 `yaml:"-" json:"-"` // this is added internally
	Summary       string                 `yaml:"summary" json:"summary"`
	Description   string                 `yaml:"description" json:"description"`
	Parameters    Parameters             `yaml:"parameters" json:"parameters"`
	Tags          []string               `yaml:"tags" json:"tags"`
	Responses     map[string]*Response   `yaml:"responses" json:"responses"`
	OperationID   string                 `yaml:"operationId" json:"operationId"`
	CustomOptions map[string]interface{} `yaml:"x-options" json:"x-options"`
}

Endpoint represents an endpoint for a path in an OpenAPI spec.

type Extension

type Extension struct {
	Base   string            `json:"base" yaml:"base"`
	Fields []*ExtensionField `json:"fields" yaml:"fields"`
}

Extension is used to define Protocol Buffer extensions from within an OpenAPI spec. use `x-extentions` key.

type ExtensionField

type ExtensionField struct {
	Name   string `yaml:"name" json:"name"`
	Type   string `yaml:"type" json:"type"`
	Number int    `yaml:"number" json:"number"`
}

ExtensionField defines the fields to be added to the base message type

type GlobalOptions

type GlobalOptions map[string]string

GlobalOptions is used to store Protocol Buffers global options, such as package names

type Model

type Model struct {
	Properties map[string]*Schema `yaml:"properties" json:"properties"`
	Name       string
	Depth      int
}

Model represents a model definition from an OpenAPI spec.

type Option

type Option = option.Option

Option is used to pass options to several methods

func WithDir

func WithDir(s string) Option

WithDir returns an option to specify the directory from which external references should be resolved.

type Parameter

type Parameter struct {
	Name        string     `yaml:"name" json:"name"`
	Description string     `yaml:"description" json:"description"`
	Enum        []string   `yaml:"enum,omitempty" json:"enum,omitempty"`
	Format      string     `yaml:"format,omitempty", json:"format,omitempty"`
	In          string     `yaml:"in,omitempty" json:"in,omitempty"`
	Items       *Schema    `yaml:"items,omitempty" json:"items,omitempty"`
	ProtoTag    int        `yaml:"x-proto-tag" json:"x-proto-tag"`
	Ref         string     `yaml:"$ref" json:"$ref"`
	Required    bool       `yaml:"required,omitempty" json:"required,omitempty"`
	Schema      *Schema    `yaml:"schema,omitempty" json:"schema,omitempty"` // if in == "body", then schema is present
	Type        SchemaType `yaml:"type,omitempty" json:"type,omitempty"`
}

Parameter is a partial representation of OpenAPI parameter type (https://swagger.io/specification/#parameterObject)

type Parameters

type Parameters []*Parameter

Parameters is a slice of request parameters for a single endpoint.

type Path

type Path struct {
	Get        *Endpoint  `yaml:"get" json:"get"`
	Put        *Endpoint  `yaml:"put" json:"put"`
	Post       *Endpoint  `yaml:"post" json:"post"`
	Delete     *Endpoint  `yaml:"delete" json:"delete"`
	Parameters Parameters `yaml:"parameters" json:"parameters"`
}

Path represents all of the endpoints and parameters available for a single path.

type Response

type Response struct {
	Description string  `yaml:"description" json:"description"`
	Schema      *Schema `yaml:"schema" json:"schema"`
}

Response represents the response object in an OpenAPI spec.

type Schema

type Schema struct {

	// if this schema refers to a definition found elsewhere, this value
	// is used. Note that if present, this takes precedence over other values
	Ref string `yaml:"$ref" json:"$ref"`

	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// scalar
	// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject
	Type   SchemaType `yaml:"type" json:"type"`
	Format string     `yaml:"format,omitempty" json:"format,omitempty"`
	Enum   []string   `yaml:"enum,omitempty" json:"enum,omitempty"`

	ProtoName string `yaml:"-" json:"-"`
	ProtoTag  int    `yaml:"x-proto-tag" json:"x-proto-tag"`

	// objects
	Required             []string           `yaml:"required" json:"required"`
	Properties           map[string]*Schema `yaml:"properties" json:"properties"`
	AdditionalProperties *Schema            `yaml:"additionalProperties" json:"additionalProperties"`

	// is an array
	Items *Schema `yaml:"items" json:"items"`

	// validation (regex pattern, max/min length)
	Pattern   string `yaml:"pattern,omitempty" json:"pattern,omitempty"`
	MaxLength int    `yaml:"maxLength,omitempty" json:"maxLength,omitempty"`
	MinLength int    `yaml:"minLength,omitempty" json:"minLength,omitempty"`
	Maximum   int    `yaml:"maximum,omitempty" json:"maximum,omitempty"`
	Minimum   int    `yaml:"minimum,omitempty" json:"minimum,omitempty"`
	// contains filtered or unexported fields
}

Schema represent Model properties in an OpenAPI spec.

func (Schema) IsNil

func (s Schema) IsNil() bool

IsNil returns true if it's nil schema (e.g.: `additionalProperties: false`)

func (*Schema) UnmarshalJSON

func (s *Schema) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes JSON data into a Schema

type SchemaType

type SchemaType []string

SchemaType represents the "type" field. It may contain 0 or more basic type names.

func (*SchemaType) Contains

func (s *SchemaType) Contains(t string) bool

Contains returns true if the specified type is listed within the list of schema types

func (*SchemaType) Empty

func (s *SchemaType) Empty() bool

Empty returns true if there was no type specified

func (*SchemaType) First

func (s *SchemaType) First() string

First returns the first type listed under this SchemaType

func (*SchemaType) Len

func (s *SchemaType) Len() int

Len returns the number of types listed under this SchemaType

func (*SchemaType) UnmarshalJSON

func (s *SchemaType) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes JSON data into a SchemaType

func (*SchemaType) UnmarshalYAML

func (s *SchemaType) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML decodes YAML data into a SchemaType

type Spec

type Spec struct {
	FileName string // internal use to pass file path
	Swagger  string `yaml:"swagger" json:"swagger"`
	Info     struct {
		Title       string `yaml:"title" json:"title"`
		Description string `yaml:"description" json:"description"`
		Version     string `yaml:"version" json:"version"`
	} `yaml:"info" json:"info"`
	Host          string                `yaml:"host" json:"host"`
	Schemes       []string              `yaml:"schemes" json:"schemes"`
	BasePath      string                `yaml:"basePath" json:"basePath"`
	Produces      []string              `yaml:"produces" json:"produces"`
	Paths         map[string]*Path      `yaml:"paths" json:"paths"`
	Definitions   map[string]*Schema    `yaml:"definitions" json:"definitions"`
	Parameters    map[string]*Parameter `yaml:"parameters" json:"parameters"`
	Extensions    []*Extension          `yaml:"x-extensions" json:"x-extensions"`
	GlobalOptions GlobalOptions         `yaml:"x-global-options" json:"x-global-options"`
}

Spec is the base struct for containing OpenAPI spec declarations.

func LoadFile

func LoadFile(fn string) (*Spec, error)

LoadFile loads an OpenAPI spec from a file, or a remote HTTP(s) location. This function also resolves any external references.