Documentation
¶
Overview ¶
Package v3 represents all OpenAPI 3+ high-level models. High-level models are easy to navigate and simple to extract what ever is required from an OpenAPI 3+ specification.
High-level models are backed by low-level ones. There is a 'GoLow()' method available on every high level object. 'Going Low' allows engineers to transition from a high-level or 'porcelain' API, to a low-level 'plumbing' API, which provides fine grain detail to the underlying AST powering the data, lines, columns, raw nodes etc.
Example ¶
Creating a new high-level OpenAPI 3+ document from an OpenAPI specification.
// Load in an OpenAPI 3+ specification as a byte slice.
data, _ := ioutil.ReadFile("../../../test_specs/petstorev3.json")
// Create a new *datamodel.SpecInfo from bytes.
info, _ := datamodel.ExtractSpecInfo(data)
var err []error
// Create a new low-level Document, capture any errors thrown during creation.
lowDoc, err = lowv3.CreateDocument(info)
// Get upset if any errors were thrown.
if len(err) > 0 {
for i := range err {
fmt.Printf("error: %e", err[i])
}
panic("something went wrong")
}
// Create a high-level Document from the low-level one.
doc := NewDocument(lowDoc)
// Print out some details
fmt.Printf("Petstore contains %d paths and %d component schemas",
len(doc.Paths.PathItems), len(doc.Components.Schemas))
Output: Petstore contains 13 paths and 8 component schemas
Index ¶
- Constants
- func ExtractContent(...) map[string]*MediaType
- func ExtractEncoding(...) map[string]*Encoding
- func ExtractHeaders(...) map[string]*Header
- type Callback
- type Components
- type Document
- type Encoding
- type Header
- type Link
- type MediaType
- type OAuthFlow
- type OAuthFlows
- type Operation
- type Parameter
- type PathItem
- type Paths
- type RequestBody
- type Response
- type Responses
- type SecurityRequirement
- type SecurityScheme
- type Server
- type ServerVariable
Examples ¶
Constants ¶
const ( NameLabel = "name" DescriptionLabel = "description" ExternalDocsLabel = "externalDocs" )
Variables ¶
This section is empty.
Functions ¶
func ExtractContent ¶
func ExtractContent(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.MediaType]) map[string]*MediaType
func ExtractEncoding ¶
func ExtractEncoding(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.Encoding]) map[string]*Encoding
ExtractEncoding converts hard to navigate low-level plumbing Encoding definitions, into high-level simple map
func ExtractHeaders ¶
func ExtractHeaders(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.Header]) map[string]*Header
Types ¶
type Callback ¶
type Callback struct {
Expression map[string]*PathItem
Extensions map[string]any
// contains filtered or unexported fields
}
Callback represents a high-level Callback object for OpenAPI 3+.
func NewCallback ¶
NewCallback creates a new high-level callback from a low-level one.
type Components ¶
type Components struct {
Schemas map[string]*highbase.SchemaProxy
Responses map[string]*Response
Parameters map[string]*Parameter
Examples map[string]*highbase.Example
RequestBodies map[string]*RequestBody
Headers map[string]*Header
SecuritySchemes map[string]*SecurityScheme
Links map[string]*Link
Callbacks map[string]*Callback
Extensions map[string]any
// contains filtered or unexported fields
}
func NewComponents ¶
func NewComponents(comp *low.Components) *Components
func (*Components) GoLow ¶
func (c *Components) GoLow() *low.Components
type Document ¶
type Document struct {
// Version is the version of OpenAPI being used, extracted from the 'openapi: x.x.x' definition.
// This is not a standard property of the OpenAPI model, it's a convenience mechanism only.
Version string
// Info presents a specification Info definitions
// - https://spec.openapis.org/oas/v3.1.0#info-object
Info *base.Info
// Servers is a slice of Server instances
// - https://spec.openapis.org/oas/v3.1.0#server-object
Servers []*Server
// Paths contains all the PathItem definitions for the specification.
// - https://spec.openapis.org/oas/v3.1.0#paths-object
Paths *Paths
// Components contains everything defined as a component (referenced by everything else)
// - https://spec.openapis.org/oas/v3.1.0#components-object
Components *Components
// Security contains global security requirements/roles for the specification
// - https://spec.openapis.org/oas/v3.1.0#security-requirement-object
Security *SecurityRequirement
// Tags is a slice of base.Tag instances defined by the specification
// - https://spec.openapis.org/oas/v3.1.0#tag-object
Tags []*base.Tag
// ExternalDocs is an instance of base.ExternalDoc for.. well, obvious really, innit.
// - https://spec.openapis.org/oas/v3.1.0#external-documentation-object
ExternalDocs *base.ExternalDoc
// Extensions contains all custom extensions defined for the top-level document.
Extensions map[string]any
// JsonSchemaDialect is a 3.1+ property that sets the dialect to use for validating *base.Schema definitions
// - https://spec.openapis.org/oas/v3.1.0#schema-object
JsonSchemaDialect string
// Webhooks is a 3.1+ property that is similar to callbacks, except, this defines incoming webhooks.
Webhooks map[string]*PathItem
// Index is a reference to the *index.SpecIndex that was created for the document and used
// as a guide when building out the Document. Ideal if further processing is required on the model and
// the original details are required to continue the work.
//
// This property is not a part of the OpenAPI schema, this is custom to libopenapi.
Index *index.SpecIndex
// contains filtered or unexported fields
}
Document represents a high-level OpenAPI 3 document (both 3.0 & 3.1). A Document is the root of the specification.
func NewDocument ¶
NewDocument will create a new high-level Document from a low-level one.
type Encoding ¶
type Encoding struct {
ContentType string
Headers map[string]*Header
Style string
Explode bool
AllowReserved bool
// contains filtered or unexported fields
}
Encoding represents an OpenAPI 3+ Encoding object - https://spec.openapis.org/oas/v3.1.0#encoding-object
func NewEncoding ¶
NewEncoding creates a new instance of Encoding from a low-level one.
type Header ¶
type Header struct {
Description string
Required bool
Deprecated bool
AllowEmptyValue bool
Style string
Explode bool
AllowReserved bool
Schema *highbase.SchemaProxy
Example any
Examples map[string]*highbase.Example
Content map[string]*MediaType
Extensions map[string]any
// contains filtered or unexported fields
}
type Link ¶
type MediaType ¶
type MediaType struct {
Schema *base.SchemaProxy
Example any
Examples map[string]*base.Example
Encoding map[string]*Encoding
Extensions map[string]any
// contains filtered or unexported fields
}
func NewMediaType ¶
type OAuthFlow ¶
type OAuthFlow struct {
AuthorizationUrl string
TokenUrl string
RefreshUrl string
Scopes map[string]string
Extensions map[string]any
// contains filtered or unexported fields
}
func NewOAuthFlow ¶
type OAuthFlows ¶
type OAuthFlows struct {
Implicit *OAuthFlow
Password *OAuthFlow
ClientCredentials *OAuthFlow
AuthorizationCode *OAuthFlow
Extensions map[string]any
// contains filtered or unexported fields
}
func NewOAuthFlows ¶
func NewOAuthFlows(flows *low.OAuthFlows) *OAuthFlows
func (*OAuthFlows) GoLow ¶
func (o *OAuthFlows) GoLow() *low.OAuthFlows
type Operation ¶
type Operation struct {
Tags []string
Summary string
Description string
ExternalDocs *base.ExternalDoc
OperationId string
Parameters []*Parameter
RequestBody *RequestBody
Responses *Responses
Callbacks map[string]*Callback
Deprecated bool
Security *SecurityRequirement
Servers []*Server
Extensions map[string]any
// contains filtered or unexported fields
}
func NewOperation ¶
type Parameter ¶
type Parameter struct {
Name string
In string
Description string
Required bool
Deprecated bool
AllowEmptyValue bool
Style string
Explode bool
AllowReserved bool
Schema *base.SchemaProxy
Example any
Examples map[string]*base.Example
Content map[string]*MediaType
Extensions map[string]any
// contains filtered or unexported fields
}
func NewParameter ¶
type PathItem ¶
type PathItem struct {
Description string
Summary string
Get *Operation
Put *Operation
Post *Operation
Delete *Operation
Options *Operation
Head *Operation
Patch *Operation
Trace *Operation
Servers []*Server
Parameters []*Parameter
Extensions map[string]any
// contains filtered or unexported fields
}
func NewPathItem ¶
type Paths ¶
type RequestBody ¶
type RequestBody struct {
Description string
Content map[string]*MediaType
Required bool
Extensions map[string]any
// contains filtered or unexported fields
}
func NewRequestBody ¶
func NewRequestBody(rb *low.RequestBody) *RequestBody
func (*RequestBody) GoLow ¶
func (r *RequestBody) GoLow() *low.RequestBody
type Response ¶
type Response struct {
Description string
Headers map[string]*Header
Content map[string]*MediaType
Extensions map[string]any
Links map[string]*Link
// contains filtered or unexported fields
}
func NewResponse ¶
type Responses ¶
type Responses struct {
Codes map[string]*Response
Default *Response
// contains filtered or unexported fields
}
func NewResponses ¶
func (*Responses) FindResponseByCode ¶
type SecurityRequirement ¶
type SecurityRequirement struct {
ValueRequirements []map[string][]string
// contains filtered or unexported fields
}
func NewSecurityRequirement ¶
func NewSecurityRequirement(req *low.SecurityRequirement) *SecurityRequirement
func (*SecurityRequirement) GoLow ¶
func (s *SecurityRequirement) GoLow() *low.SecurityRequirement
type SecurityScheme ¶
type SecurityScheme struct {
Type string
Description string
Name string
In string
Scheme string
BearerFormat string
Flows *OAuthFlows
OpenIdConnectUrl string
Extensions map[string]any
// contains filtered or unexported fields
}
func NewSecurityScheme ¶
func NewSecurityScheme(ss *low.SecurityScheme) *SecurityScheme
func (*SecurityScheme) GoLow ¶
func (s *SecurityScheme) GoLow() *low.SecurityScheme
type Server ¶
type Server struct {
URL string
Description string
Variables map[string]*ServerVariable
// contains filtered or unexported fields
}
type ServerVariable ¶
type ServerVariable struct {
Enum []string
Default string
Description string
// contains filtered or unexported fields
}
func NewServerVariable ¶
func NewServerVariable(variable *low.ServerVariable) *ServerVariable
func (*ServerVariable) GoLow ¶
func (s *ServerVariable) GoLow() *low.ServerVariable