openapi3

package
v1.14.0 Latest Latest
Warning

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

 Go to latest Published: Dec 2, 2022 License: MIT Imports: 27 Imported by: 6

Documentation

Index

Constants

View Source 
const (
	TypeArray      = "array"
	TypeBoolean    = "boolean"
	TypeInteger    = "integer"
	TypeObject     = "object"
	TypeString     = "string"
	FormatDate     = "date"
	FormatDateTime = "date-time"
	FormatInt32    = "int32"
	FormatInt64    = "int64"

	PropertyOperationID = "operationId"
	PropertySummary     = "summary"
	PropertyTags        = "tags"

	InHeader = "header"
	InQuery  = "query"
	InCookie = "cookie"
)
View Source 
const (
	DescStatusIsEmpty    = 0
	DescStatusIsNotEmpty = 1
	DescStatusDefaultSep = " ~~~ "
)
View Source 
const (
	XTagGroups       = "x-tag-groups"
	XThrottlingGroup = "x-throttling-group"
)
View Source 
const (
	PathComponents = "components"
	PathParameters = "parameters"
	PathPath       = "path"
	PathSchemas    = "schemas"
)
View Source 
const (
	LocationParameter = "parameter"
	LocationRequest   = "request"
	LocationResponse  = "response"
)
View Source 
const (
	OASVersionLatest  = "3.1.0"
	OASVersionDefault = "3.0.3"
)
View Source 
const PointerComponentsSchemas = "#/components/schemas"
View Source 
const XTagGroupsPropertyName = "x-tag-groups"

Variables

View Source 
var (
	ErrPathNotFound      = errors.New("path not found")
	ErrOperationNotFound = errors.New("operation not found")
)
View Source 
var ErrJSONPointerNotParamOrSchema = errors.New("pointer is not components/parameters or components/schemas")
View Source 
var ErrOperationNotSet = errors.New("operation not set")
View Source 
var ErrSpecNotSet = errors.New("spec not set")

Functions

func BuildApiURLOAS added in v1.12.0 

func BuildApiURLOAS(specServerURL, overrideServerURL, specPath string) string

func ContentToSchemaRefMap added in v1.14.0 

func ContentToSchemaRefMap(content oas3.Content) map[string]string

func CopySchemaStandard 

func CopySchemaStandard(schema oas3.Schema) (oas3.Schema, error)

func GetExtensionPropString 

func GetExtensionPropString(xprops oas3.ExtensionProps, key string) (string, error)

GetExtensionPropString converts extension prop value from `json.RawMessage` to `string`.

func GetExtensionPropStringOrEmpty 

func GetExtensionPropStringOrEmpty(xprops oas3.ExtensionProps, key string) string

GetExtensionPropStringOrEmpty converts extension prop value from `json.RawMessage` to `string`.

func OpTableColumnsDefault 

func OpTableColumnsDefault(inclDocsURL bool) *tabulator.ColumnSet

func OpTableColumnsRingCentral 

func OpTableColumnsRingCentral() *tabulator.ColumnSet

func ReadSchemaFile added in v1.13.0 

func ReadSchemaFile(filename string) (*oas3.Schema, error)

func SchemaPointerExpand 

func SchemaPointerExpand(prefix, schemaName string) string

func SecurityRequirementsToRaw 

func SecurityRequirementsToRaw(secReqs oas3.SecurityRequirements) []map[string][]string

SecurityRequirementsToRaw returns a raw SecurityRequirements slice to be used for iterating over elements.

func TagsWithoutGroups 

func TagsWithoutGroups(spec *Spec, tagGroupSet TagGroupSet) []string

func VisitOperations 

func VisitOperations(spec *Spec, visitOp func(path, method string, op *oas3.Operation))

func VisitOperationsPathItem added in v1.8.2 

func VisitOperationsPathItem(path string, pathItem *oas3.PathItem, visitOp func(path, method string, op *oas3.Operation))

func VisitTypesFormats 

func VisitTypesFormats(spec *Spec, visitTypeFormat func(jsonPointerRoot, oasType, oasFormat string))

func WriteFileDirMerge 

func WriteFileDirMerge(outfile, inputDir string, perm os.FileMode, mergeOpts *MergeOptions) (int, error)

Types

type CollisionCheckResult 

type CollisionCheckResult int
const (
	CollisionCheckSame CollisionCheckResult = iota
	CollisionCheckOverwrite
	CollisionCheckError
	CollisionCheckSkip
)

func SchemaCheckCollisionDefault 

func SchemaCheckCollisionDefault(schemaName string, item1, item2 interface{}, item2Note string) CollisionCheckResult

func SchemaCheckCollisionSkip 

func SchemaCheckCollisionSkip(schemaName string, item1, item2 interface{}, item2Note string) CollisionCheckResult

type ExtensionPropsParent 

type ExtensionPropsParent interface{}

type JSONPointer added in v1.14.0 

type JSONPointer jsonpointer.JSONPointer

func ParseJSONPointer added in v1.14.0 

func ParseJSONPointer(s string) (JSONPointer, error)

func (*JSONPointer) IsTopParameter added in v1.14.0 

func (p *JSONPointer) IsTopParameter() (string, bool)

func (*JSONPointer) IsTopSchema added in v1.14.0 

func (p *JSONPointer) IsTopSchema() (string, bool)

type MergeOptions 

type MergeOptions struct {
	FileRx               *regexp.Regexp
	SchemaFunc           func(schemaName string, sch1, sch2 interface{}, hint2 string) CollisionCheckResult
	CollisionCheckResult CollisionCheckResult
	ValidateEach         bool
	ValidateFinal        bool
	TableColumns         *tabulator.ColumnSet
	TableOpFilterFunc    func(path, method string, op *oas3.Operation) bool
}

func NewMergeOptionsSkip 

func NewMergeOptionsSkip() *MergeOptions

func (*MergeOptions) CheckSchemaCollision 

func (mo *MergeOptions) CheckSchemaCollision(schemaName string, sch1, sch2 interface{}, hint2 string) CollisionCheckResult

type Ontology added in v1.14.0 

type Ontology struct {
	Operations  map[string]OperationMeta `json:"operationIDs"`
	SchemaNames []string                 `json:"schemaNames"`
	Parameters  oas3.ParametersMap       `json:"parameters"`
}

Ontology returns the naming structure of an OpenAPI Spec. It is useful for understanding the naming conventions of an existing OpenAPI Spec. For example, the relationship of operationIDs to paths and the relationship of parameter name component keys to parameter names.

func NewOntology added in v1.14.0 

func NewOntology() Ontology

type OntologySet added in v1.14.0 

type OntologySet struct {
	Ontologies map[string]Ontology `json:"ontologies"`
}

OntologySet is a set of ontologies which can be used to understand ontologies by a key, such as filename or by tag.

type Operation added in v1.9.1 

type Operation = oas3.Operation

type OperationMeta 

type OperationMeta struct {
	OperationID          string   `json:"operationID,omitempty"`
	DocsDescription      string   `json:"docsDescription,omitempty"`
	DocsURL              string   `json:"docsURL,omitempty"`
	Method               string   `json:"method,omitempty"`
	Path                 string   `json:"path,omitempty"`
	SecurityScopes       []string `json:"securityScopes,omitempty"`
	Summary              string   `json:"summary,omitempty"`
	Tags                 []string `json:"tags,omitempty"`
	MetaNotes            []string `json:"metaNotes,omitempty"`
	XThrottlingGroup     string   `json:"x-throttlingGroup,omitempty"`
	RequestBodySchemaRef string   `json:"requestBodySchemaRef,omitempty"`
}

OperationMeta is used to hold additional information for a spec operation.

func OperationToMeta 

func OperationToMeta(url, method string, op *oas3.Operation, inclTags []string) *OperationMeta

OperationToMeta converts a path, method and operation to an `*OperationMeta`. The function returns `nil` if any of the items are empty.

func (*OperationMeta) PathMethod added in v1.14.0 

func (om *OperationMeta) PathMethod() string

func (*OperationMeta) TrimSpace 

func (om *OperationMeta) TrimSpace()

type OperationMore added in v1.14.0 

type OperationMore struct {
	Path      string
	Method    string
	Operation *oas3.Operation
}

func (*OperationMore) ExtensionPropStringOrEmpty added in v1.14.0 

func (om *OperationMore) ExtensionPropStringOrEmpty(key string) string

ExtensionPropStringOrEmpty converts extension prop value from `json.RawMessage` to `string`.

func (*OperationMore) HasParameter added in v1.14.0 

func (om *OperationMore) HasParameter(paramNameWant string) bool

func (*OperationMore) JSONPointers added in v1.14.0 

func (om *OperationMore) JSONPointers() map[string][]string

JSONPointers returns a `map[string][]string` where the keys are JSON pointers and the value slice is a slice of locations.

func (*OperationMore) Meta added in v1.14.0 

func (om *OperationMore) Meta() *OperationMeta

func (*OperationMore) PathMethod added in v1.14.0 

func (om *OperationMore) PathMethod() string

func (*OperationMore) RequestBodySchemaRef added in v1.14.0 

func (om *OperationMore) RequestBodySchemaRef() []string

func (*OperationMore) RequestMediaTypes added in v1.14.0 

func (om *OperationMore) RequestMediaTypes() []string

RequestMediaTypes returns a sorted slice of request media types.

func (*OperationMore) ResponseMediaTypes added in v1.14.0 

func (om *OperationMore) ResponseMediaTypes() []string

ResponseMediaTypes returns a sorted slice of response media types.

func (*OperationMore) SecurityScopes added in v1.14.0 

func (om *OperationMore) SecurityScopes(fullyQualified bool) []string

SecurityScopes retrieves a flat list of security scopes for an operation.

type OperationMoreSet added in v1.14.0 

type OperationMoreSet struct {
	OperationMores []OperationMore
}

func (*OperationMoreSet) SummariesMap added in v1.14.0 

func (omSet *OperationMoreSet) SummariesMap() map[string]string

SummariesMap returns a `map[string]string` where the keys are the operation's path and method, while the values are the sumamries.`

type Spec added in v1.9.0 

type Spec = oas3.T

func Merge 

func Merge(specMaster, specExtra *Spec, specExtraNote string, mergeOpts *MergeOptions) (*Spec, error)

func MergeDirectory 

func MergeDirectory(dir string, mergeOpts *MergeOptions) (*Spec, int, error)

func MergeFiles 

func MergeFiles(filepaths []string, mergeOpts *MergeOptions) (*Spec, error)

func MergeParameters 

func MergeParameters(specMaster, specExtra *Spec, specExtraNote string, mergeOpts *MergeOptions) (*Spec, error)

func MergePaths 

func MergePaths(specMaster, specExtra *Spec) (*Spec, error)

func MergeRequestBodies 

func MergeRequestBodies(specMaster, specExtra *Spec, specExtraNote string) (*Spec, error)

func MergeResponses 

func MergeResponses(specMaster, specExtra *Spec, specExtraNote string, mergeOpts *MergeOptions) (*Spec, error)

func MergeSchemas 

func MergeSchemas(specMaster, specExtra *Spec, specExtraNote string, mergeOpts *MergeOptions) (*Spec, error)

func MergeTags 

func MergeTags(specMaster, specExtra *Spec) *Spec

func MergeWithTables 

func MergeWithTables(spec1, spec2 *Spec, specExtraNote string, mergeOpts *MergeOptions) (*Spec, []*table.Table, error)

MergeWithTables performs a spec merge and returns comparison tables. This is useful to combine with github.com/grokify/gocharts/v2/data/table WriteXLSX() to write out comparison tables for debugging.

func NewSpec 

func NewSpec(oasVersion, apiTitle, apiVersion string) *Spec

NewSpec returns a new OpenAPI 3 spec that will validate. Specifically, it includes an OAS version, sets `info` to be an empty object instead of null and sets apiVersion.

func Parse 

func Parse(oas3Bytes []byte) (*Spec, error)

Parse will parse a byte array to an `*oas3.Swagger` struct. It will use JSON first. If unsuccessful, it will attempt to parse it as YAML.

func ReadFile 

func ReadFile(oas3file string, validate bool) (*Spec, error)

ReadFile does optional validation which is useful when merging incomplete spec files.

func ReadURL 

func ReadURL(oas3url string) (*Spec, error)

type SpecMeta 

type SpecMeta struct {
	Filepath        string
	Version         int
	IsValid         bool
	ValidationError string
}

type SpecMetas 

type SpecMetas struct {
	Metas []SpecMeta
}

func ReadSpecMetasDir 

func ReadSpecMetasDir(dir string, rx *regexp.Regexp) (SpecMetas, error)

func ReadSpecMetasFiles 

func ReadSpecMetasFiles(files []string) (SpecMetas, error)

func (*SpecMetas) Filepaths 

func (metas *SpecMetas) Filepaths(validOnly bool) []string

func (*SpecMetas) Merge 

func (metas *SpecMetas) Merge(validatesOnly bool, mergeOpts *MergeOptions) (SpecMore, error)

type SpecMore 

type SpecMore struct {
	Spec *Spec
}

func MergeSpecMetas 

func MergeSpecMetas(metas *SpecMetas, validatesOnly bool, mergeOpts *MergeOptions) (SpecMore, error)

func ReadSpecMore 

func ReadSpecMore(path string, validate bool) (*SpecMore, error)

func (*SpecMore) Clone added in v1.14.0 

func (sm *SpecMore) Clone() (*Spec, error)

func (*SpecMore) ComponentRequestBody 

func (sm *SpecMore) ComponentRequestBody(componentPath string) *oas3.RequestBodyRef

func (*SpecMore) ExportByTag added in v1.14.0 

func (sm *SpecMore) ExportByTag(tag string) (*Spec, error)

ExportByTag creates an individual specs for one tag.

func (*SpecMore) ExportByTags added in v1.14.0 

func (sm *SpecMore) ExportByTags() (map[string]*Spec, error)

ExportByTags creates individual specs by tag.

func (*SpecMore) ExtensionNames 

func (sm *SpecMore) ExtensionNames() map[string]int

ExtensionNames is not complete yet.

func (*SpecMore) HasComponentSchema 

func (sm *SpecMore) HasComponentSchema(componentSchemaName string, caseInsensitiveCaseMatch bool) bool

func (*SpecMore) MarshalJSON 

func (sm *SpecMore) MarshalJSON(prefix, indent string) ([]byte, error)

func (*SpecMore) MarshalYAML added in v1.14.0 

func (sm *SpecMore) MarshalYAML() ([]byte, error)

func (*SpecMore) Ontology added in v1.14.0 

func (sm *SpecMore) Ontology() Ontology

Ontology returns a populated `Ontology` struct for the spec. If no spec is supplied, a zero value is returned.

func (*SpecMore) OperationByID 

func (sm *SpecMore) OperationByID(wantOperationID string) (path, method string, op *oas3.Operation, err error)

func (*SpecMore) OperationByPathMethod added in v1.13.0 

func (sm *SpecMore) OperationByPathMethod(path, method string) (*oas3.Operation, error)

func (*SpecMore) OperationCountsByTag 

func (sm *SpecMore) OperationCountsByTag() *histogram.Histogram

OperationCountsByTag returns a histogram for operations by tag.

func (*SpecMore) OperationIDs added in v1.12.3 

func (sm *SpecMore) OperationIDs() []string

func (*SpecMore) OperationIDsCounts added in v1.13.0 

func (sm *SpecMore) OperationIDsCounts() map[string]int

func (*SpecMore) OperationIDsLocations added in v1.13.0 

func (sm *SpecMore) OperationIDsLocations() map[string][]string

OperationIDsLocations returns a `map[string][]string` where the keys are operationIDs and the values are pathMethods for use in analyzing if there are duplicate operationIDs.

func (*SpecMore) OperationMetas 

func (sm *SpecMore) OperationMetas(inclTags []string) []OperationMeta

func (*SpecMore) OperationMetasMap added in v1.14.0 

func (sm *SpecMore) OperationMetasMap(inclTags []string) map[string]OperationMeta

func (*SpecMore) OperationParametersDescriptionStatus 

func (sm *SpecMore) OperationParametersDescriptionStatus() maputil.MapStringMapStringInt

OperationParametersDescriptionStatus returns a set of operationIds and parameters with description status where `1` indicates a description and `0` indicates no descriptions. Descriptions for references aren't processed so they aren't analyzed and reported on. This returns a `MapStringMapStringInt` where the first key is the operationIds and the second key is the parameter name.

func (*SpecMore) OperationParametersDescriptionStatusCounts 

func (sm *SpecMore) OperationParametersDescriptionStatusCounts() (with, without, all int)

OperationParametersDescriptionStatusCounts returns operation parameter counts with descriptions, without descriptions, and total counts.

func (*SpecMore) OperationParametersWithoutDescriptionsWriteFile 

func (sm *SpecMore) OperationParametersWithoutDescriptionsWriteFile(filename string) error

func (*SpecMore) Operations added in v1.14.0 

func (sm *SpecMore) Operations(inclTags []string) *OperationMoreSet

func (*SpecMore) OperationsCount 

func (sm *SpecMore) OperationsCount() int

func (*SpecMore) OperationsDescriptionInfo added in v1.13.0 

func (sm *SpecMore) OperationsDescriptionInfo() map[string][]string

OperationsDescriptionInfo returns information on operations with and without descriptions.

func (*SpecMore) OperationsTable 

func (sm *SpecMore) OperationsTable(columns *tabulator.ColumnSet, filterFunc func(path, method string, op *oas3.Operation) bool) (*table.Table, error)

func (*SpecMore) ParameterNames added in v1.14.0 

func (sm *SpecMore) ParameterNames() map[string][]string

ParameterNames returns a `map[string][]string` where they key is the key in `#/components/parameters` and the values are both references and names. There should only be either a reference or a name but this structure allows capture of both.

func (*SpecMore) PrintJSON 

func (sm *SpecMore) PrintJSON(prefix, indent string) error

func (*SpecMore) SchemaNameExists 

func (sm *SpecMore) SchemaNameExists(schemaName string, includeNil bool) bool

func (*SpecMore) SchemaNames 

func (sm *SpecMore) SchemaNames() []string

func (*SpecMore) SchemaNamesStatus added in v1.7.0 

func (sm *SpecMore) SchemaNamesStatus() (schemaNoReference, both, referenceNoSchema []string, err error)

func (*SpecMore) SchemaPointers added in v1.7.0 

func (sm *SpecMore) SchemaPointers(dedupe bool) ([]string, []string, error)

func (*SpecMore) SchemaPropertiesDescriptionStatus 

func (sm *SpecMore) SchemaPropertiesDescriptionStatus() maputil.MapStringMapStringInt

SchemaPropertiesDescriptionStatus returns a set of schema names and properties with description status where `1` indicates a description and `0` indicates no descriptions. Descriptions for references aren't processed so they aren't analyzed and reported on. This returns a `MapStringMapStringInt` where the first key is the component name and the second key is the property name.

func (*SpecMore) SchemaPropertiesDescriptionStatusCounts 

func (sm *SpecMore) SchemaPropertiesDescriptionStatusCounts() (with, without, all int)

SchemaPropertiesDescriptionStatusCounts returns schema property counts with descriptions, without descriptions, and total counts.

func (*SpecMore) SchemaPropertiesWithoutDescriptionsWriteFile 

func (sm *SpecMore) SchemaPropertiesWithoutDescriptionsWriteFile(filename string) error

func (*SpecMore) SchemaRef 

func (sm *SpecMore) SchemaRef(schemaName string) *oas3.SchemaRef

SchemaRef returns a top level `SchemaRef` under `Components` based on map name or JSON pointer. It returns `nil` if the `schemaName` is not found.

func (*SpecMore) SchemaRefSet added in v1.14.0 

func (sm *SpecMore) SchemaRefSet(schemaName string, schemaRef *oas3.SchemaRef) error

func (*SpecMore) SchemasCopyJSONPointer added in v1.14.0 

func (sm *SpecMore) SchemasCopyJSONPointer(destSpec *Spec, jsonPointer string) error

func (*SpecMore) SchemasCopyOperation added in v1.14.0 

func (sm *SpecMore) SchemasCopyOperation(destSpec *Spec, op *oas3.Operation) error

func (*SpecMore) SchemasCopySchemaRef added in v1.14.0 

func (sm *SpecMore) SchemasCopySchemaRef(destSpec *Spec, schRef *oas3.SchemaRef) error

func (*SpecMore) SchemasCount 

func (sm *SpecMore) SchemasCount() int

func (*SpecMore) ServerURL 

func (sm *SpecMore) ServerURL(index uint) string

ServerURL returns the OAS3 Spec URL for the index specified.

func (*SpecMore) ServerURLBasePath 

func (sm *SpecMore) ServerURLBasePath(index uint) (string, error)

ServerURLBasePath extracts the base path from a OAS URL which can include variables.

func (*SpecMore) SetOperation 

func (sm *SpecMore) SetOperation(path, method string, op *oas3.Operation)

func (*SpecMore) SpecTagStats added in v1.13.0 

func (sm *SpecMore) SpecTagStats() SpecTagStats

func (*SpecMore) Stats 

func (sm *SpecMore) Stats() SpecStats

func (*SpecMore) StatusCodesHistogram added in v1.10.0 

func (sm *SpecMore) StatusCodesHistogram() *histogram.HistogramSets

func (*SpecMore) TagGroups 

func (sm *SpecMore) TagGroups() (TagGroupSet, error)

TagGroups parses a TagGroupSet from an OpenAPI3 spec.

func (*SpecMore) Tags 

func (sm *SpecMore) Tags(inclTop, inclOps bool) []string

func (*SpecMore) TagsMap 

func (sm *SpecMore) TagsMap(inclTop, inclOps bool) map[string]int

TagsMap returns a set of operations with tags present in the current spec.

func (*SpecMore) TagsValidate added in v1.14.0 

func (sm *SpecMore) TagsValidate() bool

TagsValidate checks to see if the tag names in the Spec tags property and operations match.

func (*SpecMore) WriteFileCSV 

func (sm *SpecMore) WriteFileCSV(filename string) error

func (*SpecMore) WriteFileJSON 

func (sm *SpecMore) WriteFileJSON(filename string, perm os.FileMode, prefix, indent string) error

func (*SpecMore) WriteFileXLSX 

func (sm *SpecMore) WriteFileXLSX(filename string, columns *tabulator.ColumnSet, filterFunc func(path, method string, op *oas3.Operation) bool) error

func (*SpecMore) WriteFileXLSXOperationStatusCodes added in v1.10.0 

func (sm *SpecMore) WriteFileXLSXOperationStatusCodes(filename string) error

func (*SpecMore) WriteFileYAML added in v1.14.0 

func (sm *SpecMore) WriteFileYAML(filename string, perm os.FileMode) error

type SpecStats 

type SpecStats struct {
	OperationsCount int
	SchemasCount    int
}

type SpecTagCounts added in v1.13.0 

type SpecTagCounts struct {
	OpsWithTags    int
	OpsWithoutTags int
	OpsTotal       int
}

type SpecTagStats added in v1.13.0 

type SpecTagStats struct {
	TagStats      SpecTagCounts
	TagsAll       []string
	TagsMeta      []string
	TagsOps       []string
	TagCountsAll  map[string]int
	TagCountsMeta map[string]int
	TagCountsOps  map[string]int
}

type TagGroup 

type TagGroup struct {
	Name    string   `json:"name"`
	Popular bool     `json:"popular"`
	Tags    []string `json:"tags"`
}

type TagGroupSet 

type TagGroupSet struct {
	TagGroups []TagGroup
}

func NewTagGroupSet 

func NewTagGroupSet() TagGroupSet

func (*TagGroupSet) AddToSpec 

func (set *TagGroupSet) AddToSpec(spec *Spec) error

func (*TagGroupSet) Exists 

func (set *TagGroupSet) Exists(tagName string) bool

func (*TagGroupSet) GetTagGroupNamesForTagNames 

func (set *TagGroupSet) GetTagGroupNamesForTagNames(wantTagNames ...string) []string

type TagsMore 

type TagsMore struct {
	Tags oas3.Tags
}

func (*TagsMore) Get 

func (tg *TagsMore) Get(tagName string) *oas3.Tag

type ValidationStatus 

type ValidationStatus struct {
	Status  bool
	Message string
	Context string
	OpenAPI string
}

func ValidateMore 

func ValidateMore(spec *Spec) (ValidationStatus, error)

Source Files

View all Source files

Directories

Path Synopsis
apiregistry

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.