Documentation
¶
Overview ¶
Package schema provides Go types for the OpenAPI 3.1 specification.
Only the subset of the specification needed by this project is implemented: top-level Spec, Info, Server, Paths, PathItem, Operation, RequestBody and MediaType.
Reference: https://spec.openapis.org/oas/v3.1.1
Index ¶
Constants ¶
const ( // Version is the OpenAPI specification version used by this package. Version = "3.1.1" // https://swagger.io/specification/ // ParameterInPath is used for path parameters such as {id}. ParameterInPath = "path" // ParameterInQuery is used for query string parameters. ParameterInQuery = "query" // ParameterInHeader is used for header parameters. ParameterInHeader = "header" // ParameterInCookie is used for cookie parameters. ParameterInCookie = "cookie" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Info ¶
type Info struct {
Title string `json:"title" yaml:"title"` // Required.
Summary string `json:"summary,omitzero" yaml:"summary,omitempty"`
Description string `json:"description,omitzero" yaml:"description,omitempty"`
Version string `json:"version" yaml:"version"` // Required.
}
Info provides metadata about the API.
type MediaType ¶ added in v1.6.14
type MediaType struct {
Schema *jsonschema.Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
}
MediaType provides the schema for a specific content-type in a RequestBody.
func (MediaType) MarshalYAML ¶ added in v1.6.14
MarshalYAML serialises MediaType via its JSON form so that the nested *jsonschema.Schema is rendered compactly (only non-zero fields, using JSON omitempty tags that the third-party type provides).
type Operation ¶
type Operation struct {
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
Summary string `json:"summary,omitzero" yaml:"summary,omitempty"`
Description string `json:"description,omitzero" yaml:"description,omitempty"`
Parameters []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
Responses map[string]Response `json:"responses,omitempty" yaml:"responses,omitempty"`
}
Operation describes a single API operation on a path.
type Parameter ¶ added in v1.6.14
type Parameter struct {
Name string `json:"name" yaml:"name"` // Required.
In string `json:"in" yaml:"in"` // Required: "path", "query", "header", "cookie".
Description string `json:"description,omitzero" yaml:"description,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
Schema *jsonschema.Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
}
Parameter describes a single operation parameter (path, query, header or cookie).
func (Parameter) MarshalYAML ¶ added in v1.6.14
MarshalYAML serialises Parameter via its JSON form for the same reason as MediaType.MarshalYAML.
type PathItem ¶
type PathItem struct {
Summary string `json:"summary,omitzero" yaml:"summary,omitempty"`
Description string `json:"description,omitzero" yaml:"description,omitempty"`
Get *Operation `json:"get,omitempty" yaml:"get,omitempty"`
Put *Operation `json:"put,omitempty" yaml:"put,omitempty"`
Post *Operation `json:"post,omitempty" yaml:"post,omitempty"`
Delete *Operation `json:"delete,omitempty" yaml:"delete,omitempty"`
Options *Operation `json:"options,omitempty" yaml:"options,omitempty"`
Head *Operation `json:"head,omitempty" yaml:"head,omitempty"`
Patch *Operation `json:"patch,omitempty" yaml:"patch,omitempty"`
Trace *Operation `json:"trace,omitempty" yaml:"trace,omitempty"`
}
PathItem describes the operations available on a single path.
type Paths ¶
type Paths struct {
MapOfPathItemValues map[string]PathItem `json:"-" yaml:"-"` // Key must match pattern: `^/`.
}
Paths holds the relative paths to the individual endpoints and their operations. The map keys must begin with a forward slash.
func (Paths) MarshalJSON ¶
MarshalJSON serialises Paths as a flat JSON object keyed by path.
func (Paths) MarshalYAML ¶ added in v1.6.14
MarshalYAML serialises Paths as a flat YAML mapping keyed by path.
func (*Paths) UnmarshalJSON ¶
UnmarshalJSON deserialises a flat JSON object into Paths.
type RequestBody ¶ added in v1.6.14
type RequestBody struct {
Description string `json:"description,omitzero" yaml:"description,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
Content map[string]MediaType `json:"content" yaml:"content"`
}
RequestBody describes the body of a request for an Operation.
type Response ¶ added in v1.6.14
type Response struct {
Description string `json:"description" yaml:"description"` // Required.
Content map[string]MediaType `json:"content,omitempty" yaml:"content,omitempty"`
}
Response describes a single response from an Operation.
func ErrorResponse ¶ added in v1.6.14
ErrorResponse returns a Response whose schema matches the JSON error body returned by all handlers that use httpresponse.Error. Use the key "default" (catches any undeclared status code) or a specific code like "400".
type Server ¶
type Server struct {
URL string `json:"url" yaml:"url"` // Required. Format: uri-reference.
Description string `json:"description,omitzero" yaml:"description,omitempty"`
}
Server represents a server that hosts the API.
type Spec ¶
type Spec struct {
Openapi string `json:"openapi" yaml:"openapi"`
Info Info `json:"info" yaml:"info"` // Required.
JSONSchemaDialect string `json:"jsonSchemaDialect,omitzero" yaml:"jsonSchemaDialect,omitempty"` // Format: uri.
Servers []Server `json:"servers,omitempty" yaml:"servers,omitempty"`
Tags []Tag `json:"tags,omitempty" yaml:"tags,omitempty"`
Paths *Paths `json:"paths,omitempty" yaml:"paths,omitempty"`
}
Spec is the root object of an OpenAPI 3.1 document.
func NewSpec ¶
NewSpec returns a new Spec initialised with the given API title, version and the current OpenAPI Version.
func (*Spec) AddPath ¶
AddPath registers a PathItem under the given path. If item is nil the call is a no-op. Adding a path that already exists replaces the previous entry.
func (*Spec) AddTag ¶ added in v1.6.14
AddTag appends a named tag to the spec's top-level tag list, which groups operations in documentation tools such as Redoc and Swagger UI. If a tag with the same name already exists it is replaced.
func (*Spec) SetServers ¶
SetServers replaces the servers list in the spec.
func (*Spec) SetSummary ¶ added in v1.6.14
SetSummary sets the summary field of the spec's Info object.
Source Files