Help us shape the future of Go! Take the 2026 Go Developer Survey

openapi2

package
v0.151.0 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 10 Imported by: 166

Documentation

Overview

Package openapi2 parses and writes OpenAPIv2 specification documents.

Does not cover all elements of OpenAPIv2. When OpenAPI version 3 is backwards-compatible with version 2, version 3 elements have been used.

See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

Example 
package main

import (
	"encoding/json"
	"fmt"
	"os"
	"reflect"

	"github.com/oasdiff/yaml"

	"github.com/getkin/kin-openapi/openapi2"
)

func main() {
	input, err := os.ReadFile("testdata/swagger.json")
	if err != nil {
		panic(err)
	}

	var doc openapi2.T
	if err = json.Unmarshal(input, &doc); err != nil {
		panic(err)
	}
	if doc.ExternalDocs.Description != "Find out more about Swagger" {
		panic(`doc.ExternalDocs was parsed incorrectly!`)
	}

	outputJSON, err := json.Marshal(doc)
	if err != nil {
		panic(err)
	}
	var docAgainFromJSON openapi2.T
	if err = json.Unmarshal(outputJSON, &docAgainFromJSON); err != nil {
		panic(err)
	}
	if !reflect.DeepEqual(doc, docAgainFromJSON) {
		fmt.Println("objects doc & docAgainFromJSON should be the same")
	}

	outputYAML, err := yaml.Marshal(doc)
	if err != nil {
		panic(err)
	}
	var docAgainFromYAML openapi2.T
	if _, err = yaml.Unmarshal(outputYAML, &docAgainFromYAML, yaml.DecodeOpts{DisableTimestamps: true}); err != nil {
		panic(err)
	}
	if !reflect.DeepEqual(doc, docAgainFromYAML) {
		fmt.Println("objects doc & docAgainFromYAML should be the same")
	}

}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types 

type Header struct {
	Parameter
}

func (Header) MarshalJSON added in v0.43.0 

func (header Header) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of Header.

func (*Header) UnmarshalJSON added in v0.43.0 

func (header *Header) UnmarshalJSON(data []byte) error

UnmarshalJSON sets Header to a copy of data.

type Operation 

type Operation struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	Summary      string                 `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description  string                 `json:"description,omitempty" yaml:"description,omitempty"`
	Deprecated   bool                   `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	ExternalDocs *openapi3.ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	Tags         []string               `json:"tags,omitempty" yaml:"tags,omitempty"`
	OperationID  string                 `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters   Parameters             `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Responses    *Responses             `json:"responses" yaml:"responses"`
	Consumes     []string               `json:"consumes,omitempty" yaml:"consumes,omitempty"`
	Produces     []string               `json:"produces,omitempty" yaml:"produces,omitempty"`
	Schemes      []string               `json:"schemes,omitempty" yaml:"schemes,omitempty"`
	Security     *SecurityRequirements  `json:"security,omitempty" yaml:"security,omitempty"`
}

func (Operation) MarshalJSON added in v0.14.0 

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

MarshalJSON returns the JSON encoding of Operation.

func (*Operation) UnmarshalJSON added in v0.14.0 

func (operation *Operation) UnmarshalJSON(data []byte) error

UnmarshalJSON sets Operation to a copy of data.

type Parameter 

type Parameter struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	In               string          `json:"in,omitempty" yaml:"in,omitempty"`
	Name             string          `json:"name,omitempty" yaml:"name,omitempty"`
	Description      string          `json:"description,omitempty" yaml:"description,omitempty"`
	CollectionFormat string          `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"`
	Type             *openapi3.Types `json:"type,omitempty" yaml:"type,omitempty"`
	Format           string          `json:"format,omitempty" yaml:"format,omitempty"`
	Pattern          string          `json:"pattern,omitempty" yaml:"pattern,omitempty"`
	AllowEmptyValue  bool            `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Required         bool            `json:"required,omitempty" yaml:"required,omitempty"`
	UniqueItems      bool            `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	ExclusiveMin     bool            `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	ExclusiveMax     bool            `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Schema           *SchemaRef      `json:"schema,omitempty" yaml:"schema,omitempty"`
	Items            *SchemaRef      `json:"items,omitempty" yaml:"items,omitempty"`
	Enum             []any           `json:"enum,omitempty" yaml:"enum,omitempty"`
	MultipleOf       *float64        `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Minimum          *float64        `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	Maximum          *float64        `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	MaxLength        *uint64         `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MaxItems         *uint64         `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinLength        uint64          `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	MinItems         uint64          `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	Default          any             `json:"default,omitempty" yaml:"default,omitempty"`
}

func (Parameter) MarshalJSON added in v0.14.0 

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

MarshalJSON returns the JSON encoding of Parameter.

func (*Parameter) UnmarshalJSON added in v0.14.0 

func (parameter *Parameter) UnmarshalJSON(data []byte) error

UnmarshalJSON sets Parameter to a copy of data.

type Parameters 

type Parameters []*Parameter

type PathItem 

type PathItem struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	Delete     *Operation `json:"delete,omitempty" yaml:"delete,omitempty"`
	Get        *Operation `json:"get,omitempty" yaml:"get,omitempty"`
	Head       *Operation `json:"head,omitempty" yaml:"head,omitempty"`
	Options    *Operation `json:"options,omitempty" yaml:"options,omitempty"`
	Patch      *Operation `json:"patch,omitempty" yaml:"patch,omitempty"`
	Post       *Operation `json:"post,omitempty" yaml:"post,omitempty"`
	Put        *Operation `json:"put,omitempty" yaml:"put,omitempty"`
	Parameters Parameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

func (*PathItem) GetOperation 

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

func (PathItem) MarshalJSON added in v0.14.0 

func (pathItem PathItem) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of PathItem.

func (*PathItem) Operations 

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

func (*PathItem) SetOperation 

func (pathItem *PathItem) SetOperation(method string, operation *Operation)

func (*PathItem) UnmarshalJSON added in v0.14.0 

func (pathItem *PathItem) UnmarshalJSON(data []byte) error

UnmarshalJSON sets PathItem to a copy of data.

type Ref added in v0.128.0 

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

Ref is specified by OpenAPI/Swagger 2.0 standard. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#reference-object

type Response 

type Response struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	Description string             `json:"description,omitempty" yaml:"description,omitempty"`
	Schema      *SchemaRef         `json:"schema,omitempty" yaml:"schema,omitempty"`
	Headers     map[string]*Header `json:"headers,omitempty" yaml:"headers,omitempty"`
	Examples    map[string]any     `json:"examples,omitempty" yaml:"examples,omitempty"`
}

func (Response) MarshalJSON added in v0.14.0 

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

MarshalJSON returns the JSON encoding of Response.

func (*Response) UnmarshalJSON added in v0.14.0 

func (response *Response) UnmarshalJSON(data []byte) error

UnmarshalJSON sets Response to a copy of data.

type Responses added in v0.150.0 

type Responses struct {
	Extensions map[string]any `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Responses is specified by OpenAPI/Swagger 2.0 standard. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responses-object

func NewResponsesWithCapacity added in v0.150.0 

func NewResponsesWithCapacity(cap int) *Responses

NewResponsesWithCapacity builds a responses object of the given capacity.

func (*Responses) Delete added in v0.150.0 

func (responses *Responses) Delete(key string)

Delete removes the entry associated with key 'key' from 'responses'.

func (*Responses) Len added in v0.150.0 

func (responses *Responses) Len() int

Len returns the amount of keys in responses excluding responses.Extensions.

func (*Responses) Map added in v0.150.0 

func (responses *Responses) Map() map[string]*Response

Map returns responses as a 'map'. Note: iteration on Go maps is not ordered.

func (Responses) MarshalJSON added in v0.150.0 

func (responses Responses) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of Responses.

func (*Responses) Set added in v0.150.0 

func (responses *Responses) Set(key string, value *Response)

Set adds or replaces key 'key' of 'responses' with 'value'. Note: 'responses' MUST be non-nil

func (*Responses) UnmarshalJSON added in v0.150.0 

func (responses *Responses) UnmarshalJSON(data []byte) error

UnmarshalJSON sets Responses to a copy of data.

func (*Responses) Value added in v0.150.0 

func (responses *Responses) Value(key string) *Response

Value returns the response for key or nil

type Schema added in v0.128.0 

type Schema struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	AllOf        SchemaRefs             `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	Not          *SchemaRef             `json:"not,omitempty" yaml:"not,omitempty"`
	Type         *openapi3.Types        `json:"type,omitempty" yaml:"type,omitempty"`
	Title        string                 `json:"title,omitempty" yaml:"title,omitempty"`
	Format       string                 `json:"format,omitempty" yaml:"format,omitempty"`
	Description  string                 `json:"description,omitempty" yaml:"description,omitempty"`
	Enum         []any                  `json:"enum,omitempty" yaml:"enum,omitempty"`
	Default      any                    `json:"default,omitempty" yaml:"default,omitempty"`
	Example      any                    `json:"example,omitempty" yaml:"example,omitempty"`
	ExternalDocs *openapi3.ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`

	// Array-related, here for struct compactness
	UniqueItems bool `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	// Number-related, here for struct compactness
	ExclusiveMin bool `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	ExclusiveMax bool `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	// Properties
	ReadOnly        bool          `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	WriteOnly       bool          `json:"writeOnly,omitempty" yaml:"writeOnly,omitempty"`
	AllowEmptyValue bool          `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Deprecated      bool          `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	XML             *openapi3.XML `json:"xml,omitempty" yaml:"xml,omitempty"`

	// Number
	Min        *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	Max        *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	MultipleOf *float64 `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`

	// String
	MinLength uint64  `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	MaxLength *uint64 `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	Pattern   string  `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// Array
	MinItems uint64     `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	MaxItems *uint64    `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	Items    *SchemaRef `json:"items,omitempty" yaml:"items,omitempty"`

	// Object
	Required             []string                      `json:"required,omitempty" yaml:"required,omitempty"`
	Properties           Schemas                       `json:"properties,omitempty" yaml:"properties,omitempty"`
	MinProps             uint64                        `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`
	MaxProps             *uint64                       `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	AdditionalProperties openapi3.AdditionalProperties `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	Discriminator        string                        `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
}

Schema is specified by OpenAPI/Swagger 2.0 standard. See https://swagger.io/specification/v2/#schema-object

func (Schema) MarshalJSON added in v0.128.0 

func (schema Schema) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of Schema.

func (Schema) MarshalYAML added in v0.128.0 

func (schema Schema) MarshalYAML() (any, error)

MarshalYAML returns the YAML encoding of Schema.

func (*Schema) UnmarshalJSON added in v0.128.0 

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

UnmarshalJSON sets Schema to a copy of data.

type SchemaRef added in v0.128.0 

type SchemaRef struct {
	// Extensions only captures fields starting with 'x-' as no other fields
	// are allowed by the openapi spec.
	Extensions map[string]any

	Ref   string
	Value *Schema
	// contains filtered or unexported fields
}

SchemaRef represents either a Schema or a $ref to a Schema. When serializing and both fields are set, Ref is preferred over Value.

func (*SchemaRef) CollectionName added in v0.128.0 

func (x *SchemaRef) CollectionName() string

CollectionName returns the JSON string used for a collection of these components.

func (*SchemaRef) JSONLookup added in v0.128.0 

func (x *SchemaRef) JSONLookup(token string) (any, error)

JSONLookup implements https://pkg.go.dev/github.com/go-openapi/jsonpointer#JSONPointable

func (SchemaRef) MarshalJSON added in v0.128.0 

func (x SchemaRef) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of SchemaRef.

func (SchemaRef) MarshalYAML added in v0.128.0 

func (x SchemaRef) MarshalYAML() (any, error)

MarshalYAML returns the YAML encoding of SchemaRef.

func (*SchemaRef) RefPath added in v0.128.0 

func (x *SchemaRef) RefPath() *url.URL

RefPath returns the path of the $ref relative to the root document.

func (*SchemaRef) RefString added in v0.128.0 

func (x *SchemaRef) RefString() string

RefString returns the $ref value.

func (*SchemaRef) UnmarshalJSON added in v0.128.0 

func (x *SchemaRef) UnmarshalJSON(data []byte) error

UnmarshalJSON sets SchemaRef to a copy of data.

type SchemaRefs added in v0.128.0 

type SchemaRefs []*SchemaRef

type Schemas added in v0.128.0 

type Schemas map[string]*SchemaRef

type SecurityRequirements 

type SecurityRequirements []map[string][]string

type SecurityScheme 

type SecurityScheme struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	Description      string            `json:"description,omitempty" yaml:"description,omitempty"`
	Type             string            `json:"type,omitempty" yaml:"type,omitempty"`
	In               string            `json:"in,omitempty" yaml:"in,omitempty"`
	Name             string            `json:"name,omitempty" yaml:"name,omitempty"`
	Flow             string            `json:"flow,omitempty" yaml:"flow,omitempty"`
	AuthorizationURL string            `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
	Scopes           map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	Tags             openapi3.Tags     `json:"tags,omitempty" yaml:"tags,omitempty"`
}

func (SecurityScheme) MarshalJSON added in v0.14.0 

func (securityScheme SecurityScheme) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of SecurityScheme.

func (*SecurityScheme) UnmarshalJSON added in v0.14.0 

func (securityScheme *SecurityScheme) UnmarshalJSON(data []byte) error

UnmarshalJSON sets SecurityScheme to a copy of data.

type T added in v0.61.0 

type T struct {
	Extensions map[string]any `json:"-" yaml:"-"`

	Swagger             string                     `json:"swagger" yaml:"swagger"` // required
	Info                openapi3.Info              `json:"info" yaml:"info"`       // required
	ExternalDocs        *openapi3.ExternalDocs     `json:"externalDocs,omitempty" yaml:"externalDocs,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"`
	Host                string                     `json:"host,omitempty" yaml:"host,omitempty"`
	BasePath            string                     `json:"basePath,omitempty" yaml:"basePath,omitempty"`
	Paths               map[string]*PathItem       `json:"paths,omitempty" yaml:"paths,omitempty"`
	Definitions         map[string]*SchemaRef      `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]*SecurityScheme `json:"securityDefinitions,omitempty" yaml:"securityDefinitions,omitempty"`
	Security            SecurityRequirements       `json:"security,omitempty" yaml:"security,omitempty"`
	Tags                openapi3.Tags              `json:"tags,omitempty" yaml:"tags,omitempty"`
}

T is the root of an OpenAPI v2 document

func (*T) AddOperation added in v0.61.0 

func (doc *T) AddOperation(path string, method string, operation *Operation)

func (T) MarshalJSON added in v0.61.0 

func (doc T) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of T.

func (*T) UnmarshalJSON added in v0.61.0 

func (doc *T) UnmarshalJSON(data []byte) error

UnmarshalJSON sets T to a copy of data.

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.