openapi2

package
v0.153.0 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 13 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/getkin/kin-openapi/internal/yamlconv"
	"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 := yamlconv.Marshal(doc)
	if err != nil {
		panic(err)
	}
	var docAgainFromYAML openapi2.T
	if err = yamlconv.Unmarshal(outputYAML, &docAgainFromYAML); 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

func UnmarshalFromData added in v0.153.0

func UnmarshalFromData(data []byte, doc *T) error

UnmarshalFromData loads a document from swagger 2.0 bytes in either JSON or YAML. The v3 side has Loader for this; here the whole job is the decode.

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,case:strict" yaml:"summary,omitempty"`
	Description  string                 `json:"description,omitempty,case:strict" yaml:"description,omitempty"`
	Deprecated   bool                   `json:"deprecated,omitempty,case:strict" yaml:"deprecated,omitempty"`
	ExternalDocs *openapi3.ExternalDocs `json:"externalDocs,omitempty,case:strict" yaml:"externalDocs,omitempty"`
	Tags         []string               `json:"tags,omitempty,case:strict" yaml:"tags,omitempty"`
	OperationID  string                 `json:"operationId,omitempty,case:strict" yaml:"operationId,omitempty"`
	Parameters   Parameters             `json:"parameters,omitempty,case:strict" yaml:"parameters,omitempty"`
	Responses    *Responses             `json:"responses,case:strict" yaml:"responses"`
	Consumes     []string               `json:"consumes,omitempty,case:strict" yaml:"consumes,omitempty"`
	Produces     []string               `json:"produces,omitempty,case:strict" yaml:"produces,omitempty"`
	Schemes      []string               `json:"schemes,omitempty,case:strict" yaml:"schemes,omitempty"`
	Security     *SecurityRequirements  `json:"security,omitempty,case:strict" 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,case:strict" yaml:"$ref,omitempty"`

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

	Delete     *Operation `json:"delete,omitempty,case:strict" yaml:"delete,omitempty"`
	Get        *Operation `json:"get,omitempty,case:strict" yaml:"get,omitempty"`
	Head       *Operation `json:"head,omitempty,case:strict" yaml:"head,omitempty"`
	Options    *Operation `json:"options,omitempty,case:strict" yaml:"options,omitempty"`
	Patch      *Operation `json:"patch,omitempty,case:strict" yaml:"patch,omitempty"`
	Post       *Operation `json:"post,omitempty,case:strict" yaml:"post,omitempty"`
	Put        *Operation `json:"put,omitempty,case:strict" yaml:"put,omitempty"`
	Parameters Parameters `json:"parameters,omitempty,case:strict" 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,case:strict" 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,case:strict" yaml:"$ref,omitempty"`

	Description string             `json:"description,omitempty,case:strict" yaml:"description,omitempty"`
	Schema      *SchemaRef         `json:"schema,omitempty,case:strict" yaml:"schema,omitempty"`
	Headers     map[string]*Header `json:"headers,omitempty,case:strict" yaml:"headers,omitempty"`
	Examples    map[string]any     `json:"examples,omitempty,case:strict" 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) UnmarshalJSONFrom added in v0.152.0

func (responses *Responses) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom sets Responses to the next JSON value read from dec. Decoding each member from dec (rather than from a copy of its bytes) keeps the member's key in the path of any error.

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,case:strict" yaml:"allOf,omitempty"`
	Not          *SchemaRef             `json:"not,omitempty,case:strict" yaml:"not,omitempty"`
	Type         *openapi3.Types        `json:"type,omitempty,case:strict" yaml:"type,omitempty"`
	Title        string                 `json:"title,omitempty,case:strict" yaml:"title,omitempty"`
	Format       string                 `json:"format,omitempty,case:strict" yaml:"format,omitempty"`
	Description  string                 `json:"description,omitempty,case:strict" yaml:"description,omitempty"`
	Enum         []any                  `json:"enum,omitempty,case:strict" yaml:"enum,omitempty"`
	Default      any                    `json:"default,omitempty,case:strict" yaml:"default,omitempty"`
	Example      any                    `json:"example,omitempty,case:strict" yaml:"example,omitempty"`
	ExternalDocs *openapi3.ExternalDocs `json:"externalDocs,omitempty,case:strict" yaml:"externalDocs,omitempty"`

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

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

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

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

	// Object
	Required             []string                      `json:"required,omitempty,case:strict" yaml:"required,omitempty"`
	Properties           Schemas                       `json:"properties,omitempty,case:strict" yaml:"properties,omitempty"`
	MinProps             uint64                        `json:"minProperties,omitempty,case:strict" yaml:"minProperties,omitempty"`
	MaxProps             *uint64                       `json:"maxProperties,omitempty,case:strict" yaml:"maxProperties,omitempty"`
	AdditionalProperties openapi3.AdditionalProperties `json:"additionalProperties,omitempty,case:strict" yaml:"additionalProperties,omitempty"`
	Discriminator        string                        `json:"discriminator,omitempty,case:strict" 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,case:strict" yaml:"$ref,omitempty"`

	Description      string            `json:"description,omitempty,case:strict" yaml:"description,omitempty"`
	Type             string            `json:"type,omitempty,case:strict" yaml:"type,omitempty"`
	In               string            `json:"in,omitempty,case:strict" yaml:"in,omitempty"`
	Name             string            `json:"name,omitempty,case:strict" yaml:"name,omitempty"`
	Flow             string            `json:"flow,omitempty,case:strict" yaml:"flow,omitempty"`
	AuthorizationURL string            `json:"authorizationUrl,omitempty,case:strict" yaml:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty,case:strict" yaml:"tokenUrl,omitempty"`
	Scopes           map[string]string `json:"scopes,omitempty,case:strict" yaml:"scopes,omitempty"`
	Tags             openapi3.Tags     `json:"tags,omitempty,case:strict" 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,case:strict" yaml:"swagger"` // required
	Info                openapi3.Info              `json:"info,case:strict" yaml:"info"`       // required
	ExternalDocs        *openapi3.ExternalDocs     `json:"externalDocs,omitempty,case:strict" yaml:"externalDocs,omitempty"`
	Schemes             []string                   `json:"schemes,omitempty,case:strict" yaml:"schemes,omitempty"`
	Consumes            []string                   `json:"consumes,omitempty,case:strict" yaml:"consumes,omitempty"`
	Produces            []string                   `json:"produces,omitempty,case:strict" yaml:"produces,omitempty"`
	Host                string                     `json:"host,omitempty,case:strict" yaml:"host,omitempty"`
	BasePath            string                     `json:"basePath,omitempty,case:strict" yaml:"basePath,omitempty"`
	Paths               map[string]*PathItem       `json:"paths,omitempty,case:strict" yaml:"paths,omitempty"`
	Definitions         map[string]*SchemaRef      `json:"definitions,omitempty,case:strict" yaml:"definitions,omitempty"`
	Parameters          map[string]*Parameter      `json:"parameters,omitempty,case:strict" yaml:"parameters,omitempty"`
	Responses           map[string]*Response       `json:"responses,omitempty,case:strict" yaml:"responses,omitempty"`
	SecurityDefinitions map[string]*SecurityScheme `json:"securityDefinitions,omitempty,case:strict" yaml:"securityDefinitions,omitempty"`
	Security            SecurityRequirements       `json:"security,omitempty,case:strict" yaml:"security,omitempty"`
	Tags                openapi3.Tags              `json:"tags,omitempty,case:strict" 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址