Documentation
¶
Overview ¶
Package openapi20 provides parsing functionality for OpenAPI 2.0 (Swagger) specifications.
This package parses YAML or JSON documents conforming to the Swagger 2.0 specification (https://swagger.io/specification/v2/) into strongly-typed Go models defined in the github.com/apitrix/openapi-parser/models/openapi20 package.
Usage ¶
Basic parsing:
result, err := openapi20.Parse(yamlData)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Document.Info.Title)
Unknown fields are always included in the result:
result, err := openapi20.Parse(yamlData)
if err != nil {
log.Fatal(err)
}
for _, field := range result.UnknownFields {
fmt.Printf("Unknown field at %s: %s\n", field.Path, field.Name)
}
Features ¶
- Parses both JSON and YAML formats
- Preserves source location information (line/column)
- Detects unknown/unrecognized fields
- Handles x-* extension fields
- Resolves $ref references within the document
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ParseConfig ¶
type ParseConfig = shared.ParseConfig
ParseConfig controls which features are enabled during parsing. Use this alias instead of shared.ParseConfig when calling Parse, ParseReader, or ParseFile.
func All ¶
func All() *ParseConfig
All returns a config with all features enabled. This is the default when no config (nil) is passed to a Parse function.
func Defaults ¶
func Defaults(cfg *ParseConfig) *ParseConfig
Defaults returns the provided config if non-nil, otherwise All().
func FirstConfig ¶
func FirstConfig(cfgs []*ParseConfig) *ParseConfig
FirstConfig extracts the first non-nil config from a variadic list, falling back to All() if none provided.
type ParseContext ¶
type ParseContext struct {
Root *yaml.Node // Document root for $ref resolution
Definitions *yaml.Node // Cached definitions section
Parameters *yaml.Node // Cached parameters section
Responses *yaml.Node // Cached responses section
// contains filtered or unexported fields
}
ParseContext holds parsing state and provides utilities for error reporting and reference resolution. Uses a stack-based path to avoid allocations.
func (*ParseContext) CurrentPath ¶
func (ctx *ParseContext) CurrentPath() string
CurrentPath returns the current path as a dot-separated string.
func (*ParseContext) Errorf ¶
func (ctx *ParseContext) Errorf(format string, args ...interface{}) error
Errorf creates a ParseError with the current path.
func (*ParseContext) Push ¶
func (ctx *ParseContext) Push(segment string) *ParseContext
Push creates a new context with the given path segment appended. Uses a shared backing slice to avoid allocations on each call.
func (*ParseContext) UnknownFieldsResult ¶
func (ctx *ParseContext) UnknownFieldsResult() []UnknownField
UnknownFieldsResult returns all unknown fields accumulated during parsing.
type ParseError ¶
type ParseError = shared.ParseError
ParseError represents an error that occurred during parsing, including the JSON path and source location where the error occurred. This is a type alias for backward compatibility.
type ParseResult ¶
type ParseResult struct {
// Document is the parsed Swagger specification.
Document *openapi20models.Swagger
// Errors contains all flattened errors (parse errors + unknown field errors)
// collected from across the entire document tree.
Errors []*shared.ParseError
// Config is the ParseConfig that was used for this parse.
Config *ParseConfig
// contains filtered or unexported fields
}
ParseResult contains the parsed Swagger document along with any errors and unknown fields detected during parsing.
func Parse ¶
func Parse(data []byte, cfgs ...*ParseConfig) (*ParseResult, error)
Parse parses Swagger 2.0 specification from bytes (JSON or YAML). Uses yaml.Node for lossless parsing with line/column preservation. An optional ParseConfig controls which features are enabled (nil = All).
func ParseFile ¶
func ParseFile(pathOrURL string, cfgs ...*ParseConfig) (*ParseResult, error)
ParseFile parses a Swagger 2.0 specification from a file path or HTTP/HTTPS URL, resolving all $ref references relative to the source location. It auto-detects whether the input is a URL or a local file path. An optional ParseConfig controls which features are enabled (nil = All).
func ParseReader ¶
func ParseReader(r io.Reader, cfgs ...*ParseConfig) (*ParseResult, error)
ParseReader parses Swagger 2.0 specification from an io.Reader. An optional ParseConfig controls which features are enabled (nil = All).
func (*ParseResult) Wait ¶
func (r *ParseResult) Wait() error
Wait blocks until background reference resolution is complete. Returns the resolution error, if any.
type UnknownField ¶
type UnknownField = shared.UnknownField
UnknownField represents an unrecognized field found during parsing. Extension fields (x-*) are not considered unknown. This is a type alias for backward compatibility.
Source Files
¶
- config.go
- context.go
- doc.go
- errors.go
- external_docs.go
- flatten.go
- header.go
- helpers.go
- info.go
- info_contact.go
- info_license.go
- items.go
- known_fields.go
- node_helpers.go
- operation.go
- parameter.go
- parse.go
- path_item.go
- ref_parameter.go
- ref_response.go
- ref_schema.go
- resolve.go
- response.go
- schema.go
- security.go
- swagger.go
- tag.go
- unknown_fields.go
- xml.go