openapi

package
v3.20.0 Latest Latest
Warning

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

 Go to latest Published: Feb 22, 2025 License: MIT Imports: 9 Imported by: 1

Documentation

Overview

Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs.

Index

Constants

View Source 
const (
	// Array represents a JSON array.
	Array Type = "array"
	// Boolean represents a JSON boolean.
	Boolean = "boolean"
	// Integer represents a JSON number without a fraction or exponent part.
	Integer = "integer"
	// Number represents any JSON number. Number includes integer.
	Number = "number"
	// Null represents the JSON null value.
	Null = "null"
	// Object represents a JSON object.
	Object = "object"
	// String represents a JSON string.
	String = "string"
	// File is an extension used by OpenAPI to represent a file download.
	File = "file"
)
View Source 
const SchemaRef = "http://json-schema.org/draft-04/hyper-schema"

SchemaRef is the JSON Hyper-schema standard href.

Variables

View Source 
var (
	// Definitions contains the generated JSON schema definitions
	Definitions map[string]*Schema
)

Functions

func AdditionalPropertiesFromExpr added in v3.20.0 

func AdditionalPropertiesFromExpr(meta expr.MetaExpr) any

AdditionalPropertiesFromExpr extracts the OpenAPI additionalProperties.

func ExtensionsFromExpr 

func ExtensionsFromExpr(mdata expr.MetaExpr) map[string]any

ExtensionsFromExpr generates openapi extensions from the given meta expression.

func GenerateResultTypeDefinition 

func GenerateResultTypeDefinition(api *expr.APIExpr, mt *expr.ResultTypeExpr, view string)

GenerateResultTypeDefinition produces the JSON schema corresponding to the given media type and given view.

func GenerateServiceDefinition 

func GenerateServiceDefinition(api *expr.APIExpr, res *expr.HTTPServiceExpr)

GenerateServiceDefinition produces the JSON schema corresponding to the given service. It stores the results in Definitions.

func GenerateTypeDefinition 

func GenerateTypeDefinition(api *expr.APIExpr, ut *expr.UserTypeExpr)

GenerateTypeDefinition produces the JSON schema corresponding to the given type.

func GenerateTypeDefinitionWithName 

func GenerateTypeDefinitionWithName(api *expr.APIExpr, ut *expr.UserTypeExpr, typeName string)

GenerateTypeDefinitionWithName produces the JSON schema corresponding to the given type with provided type name.

func MarshalJSON added in v3.2.0 

func MarshalJSON(v any, extensions map[string]any) ([]byte, error)

MarshalJSON produces the JSON resulting from encoding an object composed of the fields in v (which must me a struct) and the keys in extensions.

func MarshalYAML added in v3.2.0 

func MarshalYAML(v any, extensions map[string]any) (any, error)

MarshalYAML produces the JSON resulting from encoding an object composed of the fields in v (which must me a struct) and the keys in extensions.

func MustGenerate added in v3.15.0 

func MustGenerate(meta expr.MetaExpr) bool

MustGenerate returns true if the meta indicates that a OpenAPI specification should be generated, false otherwise.

func ResultTypeRef 

func ResultTypeRef(api *expr.APIExpr, mt *expr.ResultTypeExpr, view string) string

ResultTypeRef produces the JSON reference to the media type definition with the given view.

func ResultTypeRefWithPrefix 

func ResultTypeRefWithPrefix(api *expr.APIExpr, mt *expr.ResultTypeExpr, view, prefix string) string

ResultTypeRefWithPrefix produces the JSON reference to the media type definition with the given view and adds the provided prefix to the type name

func TagNamesFromExpr added in v3.2.0 

func TagNamesFromExpr(mdata expr.MetaExpr) (tagNames []string)

TagNamesFromExpr computes the names of the OpenAPI tags specified in the given metadata expressions.

func ToString added in v3.2.0 

func ToString(val any) string

ToString returns the string representation of the given type.

func ToStringMap added in v3.2.0 

func ToStringMap(val any) any

ToStringMap converts map[any]any to a map[string]any when possible.

func TypeRef 

func TypeRef(api *expr.APIExpr, ut *expr.UserTypeExpr) string

TypeRef produces the JSON reference to the type definition.

func TypeRefWithPrefix 

func TypeRefWithPrefix(api *expr.APIExpr, ut *expr.UserTypeExpr, prefix string) string

TypeRefWithPrefix produces the JSON reference to the type definition and adds the provided prefix to the type name

Types

type ExternalDocs 

type ExternalDocs struct {
	Description string         `json:"description,omitempty"`
	URL         string         `json:"url,omitempty"`
	Extensions  map[string]any `json:"-" yaml:"-"`
}

ExternalDocs represents an OpenAPI External Documentation object as defined in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#externalDocumentationObject

func DocsFromExpr added in v3.2.0 

func DocsFromExpr(docs *expr.DocsExpr, meta expr.MetaExpr) *ExternalDocs

DocsFromExpr builds a ExternalDocs from the Goa docs expression. 

type Link struct {
	Title        string  `json:"title,omitempty" yaml:"title,omitempty"`
	Description  string  `json:"description,omitempty" yaml:"description,omitempty"`
	Rel          string  `json:"rel,omitempty" yaml:"rel,omitempty"`
	Href         string  `json:"href,omitempty" yaml:"href,omitempty"`
	Method       string  `json:"method,omitempty" yaml:"method,omitempty"`
	Schema       *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
	TargetSchema *Schema `json:"targetSchema,omitempty" yaml:"targetSchema,omitempty"`
	ResultType   string  `json:"mediaType,omitempty" yaml:"mediaType,omitempty"`
	EncType      string  `json:"encType,omitempty" yaml:"encType,omitempty"`
}

Link represents a "link" field in a JSON hyper schema.

type Media 

type Media struct {
	BinaryEncoding string `json:"binaryEncoding,omitempty" yaml:"binaryEncoding,omitempty"`
	Type           string `json:"type,omitempty" yaml:"type,omitempty"`
}

Media represents a "media" field in a JSON hyper schema.

type Schema 

type Schema struct {
	Schema string `json:"$schema,omitempty" yaml:"$schema,omitempty"`
	// Core schema
	ID           string             `json:"id,omitempty" yaml:"id,omitempty"`
	Title        string             `json:"title,omitempty" yaml:"title,omitempty"`
	Type         Type               `json:"type,omitempty" yaml:"type,omitempty"`
	Items        *Schema            `json:"items,omitempty" yaml:"items,omitempty"`
	Properties   map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
	Definitions  map[string]*Schema `json:"definitions,omitempty" yaml:"definitions,omitempty"`
	Description  string             `json:"description,omitempty" yaml:"description,omitempty"`
	DefaultValue any                `json:"default,omitempty" yaml:"default,omitempty"`
	Example      any                `json:"example,omitempty" yaml:"example,omitempty"`

	// Hyper schema
	Media     *Media  `json:"media,omitempty" yaml:"media,omitempty"`
	ReadOnly  bool    `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	PathStart string  `json:"pathStart,omitempty" yaml:"pathStart,omitempty"`
	Links     []*Link `json:"links,omitempty" yaml:"links,omitempty"`
	Ref       string  `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	// Validation
	Enum                 []any    `json:"enum,omitempty" yaml:"enum,omitempty"`
	Format               string   `json:"format,omitempty" yaml:"format,omitempty"`
	Pattern              string   `json:"pattern,omitempty" yaml:"pattern,omitempty"`
	ExclusiveMinimum     *float64 `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	Minimum              *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	ExclusiveMaximum     *float64 `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Maximum              *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	MinLength            *int     `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	MaxLength            *int     `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MinItems             *int     `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	MaxItems             *int     `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	Required             []string `json:"required,omitempty" yaml:"required,omitempty"`
	AdditionalProperties any      `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`

	// Union
	AnyOf []*Schema `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`

	// Extensions defines the OpenAPI extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

Schema represents an instance of a JSON schema. See http://json-schema.org/documentation.html

func APISchema 

func APISchema(api *expr.APIExpr, r *expr.RootExpr) *Schema

APISchema produces the API JSON hyper schema.

func AttributeTypeSchema 

func AttributeTypeSchema(api *expr.APIExpr, at *expr.AttributeExpr) *Schema

AttributeTypeSchema produces the JSON schema corresponding to the given attribute.

func AttributeTypeSchemaWithPrefix 

func AttributeTypeSchemaWithPrefix(api *expr.APIExpr, at *expr.AttributeExpr, prefix string) *Schema

AttributeTypeSchemaWithPrefix produces the JSON schema corresponding to the given attribute and adds the provided prefix to the type name

func NewSchema 

func NewSchema() *Schema

NewSchema instantiates a new JSON schema.

func TypeSchema 

func TypeSchema(api *expr.APIExpr, t expr.DataType) *Schema

TypeSchema produces the JSON schema corresponding to the given data type.

func TypeSchemaWithPrefix 

func TypeSchemaWithPrefix(api *expr.APIExpr, t expr.DataType, prefix string) *Schema

TypeSchemaWithPrefix produces the JSON schema corresponding to the given data type and adds the provided prefix to the type name

func (*Schema) Dup 

func (s *Schema) Dup() *Schema

Dup creates a shallow clone of the given schema.

func (*Schema) JSON 

func (s *Schema) JSON() ([]byte, error)

JSON serializes the schema into JSON. It makes sure the "$schema" standard field is set if needed prior to delegating to the standard JSON marshaler.

func (*Schema) MarshalJSON added in v3.0.7 

func (s *Schema) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of s.

func (*Schema) MarshalYAML added in v3.0.7 

func (s *Schema) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

func (*Schema) Merge 

func (s *Schema) Merge(other *Schema)

Merge does a two level deep merge of other into s.

type Tag 

type Tag struct {
	// Name of the tag.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// Description is a short description of the tag.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// ExternalDocs is additional external documentation for this tag.
	ExternalDocs *ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// Extensions defines the OpenAPI extensions.
	Extensions map[string]any `json:"-" yaml:"-"`
}

Tag allows adding meta data to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag used there.

func TagsFromExpr added in v3.2.0 

func TagsFromExpr(mdata expr.MetaExpr) (tags []*Tag)

TagsFromExpr extracts the OpenAPI related metadata from the given expression.

func (Tag) MarshalJSON 

func (t Tag) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of t.

func (Tag) MarshalYAML 

func (t Tag) MarshalYAML() (any, error)

MarshalYAML returns value which marshaled in place of the original value

type Type 

type Type string

Type is the JSON type enum.

Source Files

View all Source files

Directories

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

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.
JackTT - Gopher 🇻🇳