Categorygithub.com/go-openapi/spec
modulepackage
0.21.0
Repository: https://github.com/go-openapi/spec.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
21
Dependents
3.8k
Files
4k SLOC

# README

OpenAPI v2 object model Build Status codecov

Slack Status license Go Reference Go Report Card

The object model for OpenAPI specification documents.

FAQ

  • What does this do?
  1. This package knows how to marshal and unmarshal Swagger API specifications into a golang object model
  2. It knows how to resolve $ref and expand them to make a single root document
  • How does it play with the rest of the go-openapi packages ?
  1. This package is at the core of the go-openapi suite of packages and code generator
  2. There is a spec loading package to fetch specs as JSON or YAML from local or remote locations
  3. There is a spec validation package built on top of it
  4. There is a spec analysis package built on top of it, to analyze, flatten, fix and merge spec documents
  • Does this library support OpenAPI 3?

No. This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). There is no plan to make it evolve toward supporting OpenAPI 3.x. This discussion thread relates the full story.

An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3

  • Does the unmarshaling support YAML?

Not directly. The exposed types know only how to unmarshal from JSON.

In order to load a YAML document as a Swagger spec, you need to use the loaders provided by github.com/go-openapi/loads

Take a look at the example there: https://pkg.go.dev/github.com/go-openapi/loads#example-Spec

See also https://github.com/go-openapi/spec/issues/164

  • How can I validate a spec?

Validation is provided by the validate package

  • Why do we have an ID field for Schema which is not part of the swagger spec?

We found jsonschema compatibility more important: since id in jsonschema influences how $ref are resolved. This id does not conflict with any property named id.

See also https://github.com/go-openapi/spec/issues/23

# Functions

APIKeyAuth creates an api key auth security scheme.
ArrayProperty creates an array property.
BasicAuth creates a basic auth security scheme.
BodyParam creates a body parameter.
BooleanProperty creates a boolean property.
BoolProperty creates a boolean property.
CharProperty creates a string property.
ComposedSchema creates a schema with allOf.
DateProperty creates a date property.
DateTimeProperty creates a date time property.
ExpandParameter expands a parameter based on a basepath.
ExpandParameterWithRoot expands a parameter based on a root document, not a fetchable document.
ExpandResponse expands a response based on a basepath All refs inside response will be resolved relative to basePath.
ExpandResponseWithRoot expands a response based on a root document, not a fetchable document Notice that it is impossible to reference a json schema in a different document other than root (use ExpandResponse to resolve external references).
ExpandSchema expands the refs in the schema object with reference to the root object.
ExpandSchemaWithBasePath expands the refs in the schema object, base path configured through expand options.
ExpandSpec expands the references in a swagger spec.
FileParam creates a body parameter.
Float32Property creates a float32/float property.
Float64Property creates a float64/double property.
FormDataParam creates a body parameter.
HeaderParam creates a header parameter, this is always required by default.
Int16Property creates an int16 property.
Int32Property creates an int32 property.
Int64Property creates an int64 property.
Int8Property creates an int8 property.
JSONSchemaDraft04 loads the json schema document for json shema draft04.
MapProperty creates a map property.
MustCreateRef creates a ref object but panics when refURI is invalid.
MustLoadJSONSchemaDraft04 panics when Swagger20Schema returns an error.
MustLoadSwagger20Schema panics when Swagger20Schema returns an error.
NewItems creates a new instance of items.
NewOperation creates a new operation instance.
NewRef creates a new instance of a ref object returns an error when the reference uri is an invalid uri.
NewResponse creates a new response instance.
NewTag creates a new tag.
OAuth2AccessToken creates an access token flow oauth2 security scheme.
OAuth2Application creates an application flow oauth2 security scheme.
OAuth2Implicit creates an implicit flow oauth2 security scheme.
OAuth2Password creates a password flow oauth2 security scheme.
ParamRef creates a parameter that's a json reference.
PathParam creates a path parameter, this is always required.
QueryParam creates a query parameter.
RefProperty creates a ref property.
RefSchema creates a ref property.
ResolveItems resolves parameter items reference against a context root and base path.
ResolveItemsWithBase resolves parameter items reference against a context root and base path.
ResolveParameter resolves a parameter reference against a context root.
ResolveParameterWithBase resolves a parameter reference against a context root and base path.
ResolvePathItem resolves response a path item against a context root and base path Deprecated: use ResolvePathItemWithBase instead.
ResolvePathItemWithBase resolves response a path item against a context root and base path.
ResolveRef resolves a reference for a schema against a context root ref is guaranteed to be in root (no need to go to external files) ResolveRef is ONLY called from the code generation module.
ResolveRefWithBase resolves a reference against a context root with preservation of base path.
ResolveResponse resolves response a reference against a context root.
ResolveResponseWithBase resolves response a reference against a context root and base path.
ResponseHeader creates a new header instance for use in a response.
ResponseRef creates a response as a json reference.
SimpleArrayParam creates a param for a simple array (string, int, date etc).
StrFmtProperty creates a property for the named string format.
StringProperty creates a string property.
Swagger20Schema loads the swagger 2.0 schema from the embedded assets.

# Constants

JSONSchemaURL the url for the json schema.
SwaggerSchemaURL the url for the swagger 2.0 schema to validate specs.

# Variables

Debug is true when the SWAGGER_DEBUG env var is not empty.
ErrDerefUnsupportedType indicates that a resolved reference was found in an unsupported container type.
ErrExpandUnsupportedType indicates that $ref expansion is attempted on some invalid type.
ErrResolveRefNeedsAPointer indicates that a $ref target must be a valid JSON pointer.
ErrUnknownTypeForReference indicates that a resolved reference was found in an unsupported container type.
PathLoader is a function to use when loading remote refs.

# Structs

CommonValidations describe common JSON-schema validations.
ContactInfo contact information for the exposed API.
ContactInfoProps hold the properties of a ContactInfo object.
ExpandOptions provides options for the spec expander.
ExternalDocumentation allows referencing an external resource for extended documentation.
Header describes a header for a response of the API For more information: http://goo.gl/8us55a#headerObject.
HeaderProps describes a response header.
Info object provides metadata about the API.
InfoProps the properties for an info definition.
Items a limited subset of JSON-Schema's items object.
License information for the exposed API.
LicenseProps holds the properties of a License object.
Operation describes a single API operation on a path.
OperationProps describes an operation NOTES: - schemes, when present must be from [http, https, ws, wss]: see validate - Security is handled as a special case: see MarshalJSON function.
OrderSchemaItem holds a named schema (e.g.
Parameter a unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
ParamProps describes the specific attributes of an operation parameter NOTE: - Schema is defined when "in" == "body": see validate - AllowEmptyValue is allowed where "in" == "query" || "formData".
PathItem describes the operations available on a single path.
PathItemProps the path item specific properties.
Paths holds the relative paths to the individual endpoints.
Ref represents a json reference that is potentially resolved.
Refable is a struct for things that accept a $ref property.
Response describes a single response from an API Operation.
ResponseProps properties specific to a response.
Responses is a container for the expected responses of an operation.
ResponsesProps describes all responses for an operation.
Schema the schema object allows the definition of input and output data types.
SchemaOrArray represents a value that can either be a Schema or an array of Schema.
SchemaOrBool represents a schema or boolean value, is biased towards true for the boolean property.
SchemaOrStringArray represents a schema or a string array.
SchemaProps describes a JSON schema (draft 4).
SchemaValidations describes the validation properties of a schema NOTE: at this moment, this is not embedded in SchemaProps because this would induce a breaking change in the exported members: all initializers using litterals would fail.
SecurityScheme allows the definition of a security scheme that can be used by the operations.
SecuritySchemeProps describes a swagger security scheme in the securityDefinitions section.
SimpleSchema describe swagger simple schemas for parameters and headers.
Swagger this is the root document object for the API specification.
SwaggerProps captures the top-level properties of an Api specification NOTE: validation rules - the scheme, when present must be from [http, https, ws, wss] - BasePath must start with a leading "/" - Paths is required.
SwaggerSchemaProps are additional properties supported by swagger schemas, but not JSON-schema (draft 4).
Tag allows adding meta data to a single tag that is used by the [Operation Object](http://goo.gl/8us55a#operationObject).
TagProps describe a tag entry in the top level tags section of a swagger spec.
VendorExtensible composition block.
XMLObject a metadata object that allows for more fine-tuned XML model definitions.

# Interfaces

ResolutionCache a cache for resolving urls.

# Type aliases

Definitions contains the models explicitly defined in this spec An object to hold data types that can be consumed and produced by operations.
Dependencies represent a dependencies property.
Extensions vendor specific extensions.
OrderSchemaItems is a sortable slice of named schemas.
SchemaProperties is a map representing the properties of a Schema object.
SchemaURL represents a schema url.
SecurityDefinitions a declaration of the security schemes available to be used in the specification.
StringOrArray represents a value that can either be a string or an array of strings.