Documentation
¶
Index ¶
- Variables
- func AliasParam(comments *ast.CommentGroup) bool
- func AllOfMember(comments *ast.CommentGroup) bool
- func AllOfName(comments *ast.CommentGroup) (string, bool)
- func DefaultName(comments *ast.CommentGroup) (string, bool)
- func EnumDescExtension() string
- func EnumName(comments *ast.CommentGroup) (string, bool)
- func ExtractAnnotation(line string) (string, bool)
- func FileParam(comments *ast.CommentGroup) bool
- func GetEnumBasicLitValue(basicLit *ast.BasicLit) any
- func GetEnumDesc(extensions spec.Extensions) (desc string)
- func HasAnnotation(line string) bool
- func Ignored(comments *ast.CommentGroup) bool
- func IsAliasParam(prop ifaces.SwaggerTypable) bool
- func IsAllowedExtension(ext string) bool
- func JoinDropLast(lines []string) string
- func ModelOverride(comments *ast.CommentGroup) (string, bool)
- func NameOverride(comments *ast.CommentGroup) (string, bool)
- func ParamLocation(comments *ast.CommentGroup) (string, bool)
- func ParametersOverride(comments *ast.CommentGroup) ([]string, bool)
- func ParseEnum(val string, s *spec.SimpleSchema) []any
- func ResponseOverride(comments *ast.CommentGroup) (string, bool)
- func Rxf(rxp, ar string) *regexp.Regexp
- func Setter(target *string) func([]string)
- func StrfmtName(comments *ast.CommentGroup) (string, bool)
- func TypeName(comments *ast.CommentGroup) (string, bool)
- type ConsumesDropEmptyParser
- type MatchParamIn
- type MatchParamRequired
- type MetaSection
- type ParsedPathContent
- type PrefixRxOption
- type ProducesDropEmptyParser
- type SectionedParser
- type SectionedParserOption
- type SetCollectionFormat
- type SetDefault
- type SetDeprecatedOp
- type SetDiscriminator
- type SetEnum
- type SetExample
- type SetMaxItems
- type SetMaxLength
- type SetMaximum
- type SetMinItems
- type SetMinLength
- type SetMinimum
- type SetMultipleOf
- type SetOpExtensions
- type SetOpParams
- type SetOpResponses
- type SetPattern
- type SetReadOnlySchema
- type SetRequiredParam
- type SetRequiredSchema
- type SetSchemes
- type SetSecurity
- type SetUnique
- type TagParser
- type YAMLParser
- type YAMLParserOption
- type YAMLSpecScanner
Constants ¶
This section is empty.
Variables ¶
var ErrParser = errors.New("codescan:parsers")
ErrParser is the sentinel error for all errors originating from the parsers package.
Functions ¶
func AliasParam ¶
func AliasParam(comments *ast.CommentGroup) bool
func AllOfMember ¶
func AllOfMember(comments *ast.CommentGroup) bool
func DefaultName ¶
func DefaultName(comments *ast.CommentGroup) (string, bool)
func EnumDescExtension ¶
func EnumDescExtension() string
func ExtractAnnotation ¶
func FileParam ¶
func FileParam(comments *ast.CommentGroup) bool
func GetEnumBasicLitValue ¶
func GetEnumDesc ¶
func GetEnumDesc(extensions spec.Extensions) (desc string)
func HasAnnotation ¶
func Ignored ¶
func Ignored(comments *ast.CommentGroup) bool
func IsAliasParam ¶
func IsAliasParam(prop ifaces.SwaggerTypable) bool
func IsAllowedExtension ¶
func JoinDropLast ¶
func ModelOverride ¶
func ModelOverride(comments *ast.CommentGroup) (string, bool)
func NameOverride ¶
func NameOverride(comments *ast.CommentGroup) (string, bool)
func ParamLocation ¶
func ParamLocation(comments *ast.CommentGroup) (string, bool)
func ParametersOverride ¶
func ParametersOverride(comments *ast.CommentGroup) ([]string, bool)
func ResponseOverride ¶
func ResponseOverride(comments *ast.CommentGroup) (string, bool)
func Setter ¶
Setter sets a string field from a multi lines comment.
Usage:
Setter(&op.Description) Setter(&op.Summary)
Replaces this idiom:
parsers.WithSetDescription(func(lines []string) { op.Description = parsers.JoinDropLast(lines) }),
func StrfmtName ¶
func StrfmtName(comments *ast.CommentGroup) (string, bool)
Types ¶
type ConsumesDropEmptyParser ¶
type ConsumesDropEmptyParser struct {
// contains filtered or unexported fields
}
func NewConsumesDropEmptyParser ¶
func NewConsumesDropEmptyParser(set func([]string)) *ConsumesDropEmptyParser
type MatchParamIn ¶
type MatchParamIn struct {
// contains filtered or unexported fields
}
func NewMatchIn ¶
func NewMatchIn() *MatchParamIn
NewMatchIn returns a match-only tagger that claims `in: <location>` lines. The `in:` directive is extracted separately via parsers.ParamLocation; this tagger only prevents the line from being absorbed into the surrounding description by a SectionedParser.
func NewMatchParamIn ¶
func NewMatchParamIn(_ *oaispec.Parameter) *MatchParamIn
type MatchParamRequired ¶
type MatchParamRequired struct {
// contains filtered or unexported fields
}
func NewMatchParamRequired ¶
func NewMatchParamRequired(_ *oaispec.Parameter) *MatchParamRequired
type MetaSection ¶
type MetaSection struct {
Comments *ast.CommentGroup
}
type ParsedPathContent ¶
type ParsedPathContent struct {
Method, Path, ID string
Tags []string
Remaining *ast.CommentGroup
}
func ParseOperationPathAnnotation ¶
func ParseOperationPathAnnotation(lines []*ast.Comment) (cnt ParsedPathContent)
func ParseRoutePathAnnotation ¶
func ParseRoutePathAnnotation(lines []*ast.Comment) (cnt ParsedPathContent)
type PrefixRxOption ¶
func WithItemsPrefixLevel ¶
func WithItemsPrefixLevel(level int) PrefixRxOption
type ProducesDropEmptyParser ¶
type ProducesDropEmptyParser struct {
// contains filtered or unexported fields
}
func NewProducesDropEmptyParser ¶
func NewProducesDropEmptyParser(set func([]string)) *ProducesDropEmptyParser
type SectionedParser ¶
type SectionedParser struct {
// contains filtered or unexported fields
}
SectionedParser is the core comment-block parser for go-swagger annotations. It processes an ast.CommentGroup and splits its content into three sections:
- Header — free-form text at the top of the comment block, later split into a title and description.
- Tags — structured key:value lines (e.g. "minimum: 10", "consumes:", "schemes: http, https") recognized by registered TagParser instances.
- Annotation — an optional swagger:* annotation line (e.g. "swagger:model Foo") handled by a dedicated ifaces.ValueParser.
Parsing algorithm ¶
Parse walks each line of the comment block in order. For every line:
If the line contains a swagger:* annotation: - "swagger:ignore" → mark as ignored, stop parsing. - If an annotation parser is registered and matches → delegate to it. - Otherwise → stop parsing (the annotation belongs to a different parser).
If any registered TagParser matches the line: - For a single-line tagger: collect the line, then reset the current tagger so the next line can match a different tag. - For a multi-line tagger: the matching (header) line is consumed but NOT collected; all subsequent lines are collected into that tagger until a different tagger matches or the block ends.
Otherwise, if no tag has been seen yet, the line is appended to the header (free-form text).
After the line walk completes, three things happen:
- The header is split into title + description (see [collectScannerTitleDescription]).
- For each matched tagger, its collected lines are cleaned up (comment prefixes stripped, unless SkipCleanUp is set) and passed to the tagger's Parse method, which writes the extracted value into the target spec object.
- Title and description callbacks are invoked.
Example: Swagger meta block ¶
Given the comment block on a package doc.go:
// Petstore API. // // The purpose of this application is to provide an API for pets. // // Schemes: http, https // Host: petstore.example.com // BasePath: /v2 // Version: 1.0.0 // License: MIT http://opensource.org/licenses/MIT // Contact: John Doe <john@example.com> http://john.example.com // // Consumes: // - application/json // - application/xml // // swagger:meta
The SectionedParser (configured by NewMetaParser) will:
- Collect "Petstore API." as the title, and the next paragraph as the description (header section, lines 1-3).
- Match "Schemes: http, https" via the single-line "Schemes" tagger.
- Match "Host: ...", "BasePath: ...", etc. via their respective single-line taggers.
- Match "Consumes:" via the multi-line "Consumes" tagger, collecting "- application/json" and "- application/xml" as its body.
- Stop at "swagger:meta" (an annotation that doesn't match any registered annotation parser, so it terminates the block).
func NewMetaParser ¶
func NewMetaParser(swspec *spec.Swagger) *SectionedParser
func NewSectionedParser ¶
func NewSectionedParser(opts ...SectionedParserOption) *SectionedParser
NewSectionedParser creates a SectionedParser configured by the given options.
At minimum, callers should provide WithSetTitle and WithTaggers:
sp := NewSectionedParser(
WithSetTitle(func(lines []string) { op.Summary = JoinDropLast(lines) }),
WithSetDescription(func(lines []string) { op.Description = JoinDropLast(lines) }),
WithTaggers(
NewSingleLineTagParser("maximum", NewSetMaximum(builder)),
NewMultiLineTagParser("consumes", NewConsumesDropEmptyParser(setter), false),
),
)
func (*SectionedParser) Description ¶
func (st *SectionedParser) Description() []string
Description returns the description lines extracted from the header (everything after the title). Like SectionedParser.Title, it triggers lazy splitting on first call.
func (*SectionedParser) Ignored ¶
func (st *SectionedParser) Ignored() bool
Ignored reports whether a "swagger:ignore" annotation was encountered.
func (*SectionedParser) Parse ¶
func (st *SectionedParser) Parse(doc *ast.CommentGroup) error
Parse processes an ast.CommentGroup through the sectioned parsing algorithm described in the type documentation. Returns an error if any matched tagger's Parse method fails.
func (*SectionedParser) Title ¶
func (st *SectionedParser) Title() []string
Title returns the title lines extracted from the header. The title is separated from the description by the first blank line, or inferred from punctuation and markdown heading prefixes when there is no blank line.
Title triggers lazy title/description splitting on first call.
type SectionedParserOption ¶
type SectionedParserOption func(*SectionedParser)
SectionedParserOption configures a SectionedParser via NewSectionedParser.
func WithSetDescription ¶
func WithSetDescription(setDescription func([]string)) SectionedParserOption
WithSetDescription provides a callback that receives the extracted description lines after parsing completes.
func WithSetTitle ¶
func WithSetTitle(setTitle func([]string)) SectionedParserOption
WithSetTitle provides a callback that receives the extracted title lines after parsing completes. If no title callback is set, the parser does not attempt to separate the title from the description.
func WithTaggers ¶
func WithTaggers(taggers ...TagParser) SectionedParserOption
WithTaggers registers the TagParser instances that this SectionedParser will try to match against each line after the header section ends.
type SetCollectionFormat ¶
type SetCollectionFormat struct {
// contains filtered or unexported fields
}
func NewSetCollectionFormat ¶
func NewSetCollectionFormat(builder ifaces.OperationValidationBuilder, opts ...PrefixRxOption) *SetCollectionFormat
func (*SetCollectionFormat) Matches ¶
func (sm *SetCollectionFormat) Matches(line string) bool
func (*SetCollectionFormat) Parse ¶
func (sm *SetCollectionFormat) Parse(lines []string) error
type SetDefault ¶
type SetDefault struct {
// contains filtered or unexported fields
}
func NewSetDefault ¶
func NewSetDefault(scheme *oaispec.SimpleSchema, builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetDefault
func (*SetDefault) Matches ¶
func (sd *SetDefault) Matches(line string) bool
func (*SetDefault) Parse ¶
func (sd *SetDefault) Parse(lines []string) error
type SetDeprecatedOp ¶
type SetDeprecatedOp struct {
// contains filtered or unexported fields
}
func NewSetDeprecatedOp ¶
func NewSetDeprecatedOp(operation *oaispec.Operation) *SetDeprecatedOp
func (*SetDeprecatedOp) Matches ¶
func (su *SetDeprecatedOp) Matches(line string) bool
func (*SetDeprecatedOp) Parse ¶
func (su *SetDeprecatedOp) Parse(lines []string) error
type SetDiscriminator ¶
func NewSetDiscriminator ¶
func NewSetDiscriminator(schema *oaispec.Schema, field string) *SetDiscriminator
func (*SetDiscriminator) Matches ¶
func (su *SetDiscriminator) Matches(line string) bool
func (*SetDiscriminator) Parse ¶
func (su *SetDiscriminator) Parse(lines []string) error
type SetEnum ¶
type SetEnum struct {
// contains filtered or unexported fields
}
func NewSetEnum ¶
func NewSetEnum(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetEnum
type SetExample ¶
type SetExample struct {
// contains filtered or unexported fields
}
func NewSetExample ¶
func NewSetExample(scheme *oaispec.SimpleSchema, builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetExample
func (*SetExample) Matches ¶
func (se *SetExample) Matches(line string) bool
func (*SetExample) Parse ¶
func (se *SetExample) Parse(lines []string) error
type SetMaxItems ¶
type SetMaxItems struct {
// contains filtered or unexported fields
}
func NewSetMaxItems ¶
func NewSetMaxItems(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMaxItems
func (*SetMaxItems) Matches ¶
func (sm *SetMaxItems) Matches(line string) bool
func (*SetMaxItems) Parse ¶
func (sm *SetMaxItems) Parse(lines []string) error
type SetMaxLength ¶
type SetMaxLength struct {
// contains filtered or unexported fields
}
func NewSetMaxLength ¶
func NewSetMaxLength(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMaxLength
func (*SetMaxLength) Matches ¶
func (sm *SetMaxLength) Matches(line string) bool
func (*SetMaxLength) Parse ¶
func (sm *SetMaxLength) Parse(lines []string) error
type SetMaximum ¶
type SetMaximum struct {
// contains filtered or unexported fields
}
func NewSetMaximum ¶
func NewSetMaximum(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMaximum
func (*SetMaximum) Matches ¶
func (sm *SetMaximum) Matches(line string) bool
func (*SetMaximum) Parse ¶
func (sm *SetMaximum) Parse(lines []string) error
type SetMinItems ¶
type SetMinItems struct {
// contains filtered or unexported fields
}
func NewSetMinItems ¶
func NewSetMinItems(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMinItems
func (*SetMinItems) Matches ¶
func (sm *SetMinItems) Matches(line string) bool
func (*SetMinItems) Parse ¶
func (sm *SetMinItems) Parse(lines []string) error
type SetMinLength ¶
type SetMinLength struct {
// contains filtered or unexported fields
}
func NewSetMinLength ¶
func NewSetMinLength(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMinLength
func (*SetMinLength) Matches ¶
func (sm *SetMinLength) Matches(line string) bool
func (*SetMinLength) Parse ¶
func (sm *SetMinLength) Parse(lines []string) error
type SetMinimum ¶
type SetMinimum struct {
// contains filtered or unexported fields
}
func NewSetMinimum ¶
func NewSetMinimum(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMinimum
func (*SetMinimum) Matches ¶
func (sm *SetMinimum) Matches(line string) bool
func (*SetMinimum) Parse ¶
func (sm *SetMinimum) Parse(lines []string) error
type SetMultipleOf ¶
type SetMultipleOf struct {
// contains filtered or unexported fields
}
func NewSetMultipleOf ¶
func NewSetMultipleOf(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetMultipleOf
func (*SetMultipleOf) Matches ¶
func (sm *SetMultipleOf) Matches(line string) bool
func (*SetMultipleOf) Parse ¶
func (sm *SetMultipleOf) Parse(lines []string) error
type SetOpExtensions ¶
type SetOpExtensions struct {
Set func(*oaispec.Extensions)
Debug bool
// contains filtered or unexported fields
}
func NewSetExtensions ¶
func NewSetExtensions(setter func(*oaispec.Extensions), debug bool) *SetOpExtensions
func (*SetOpExtensions) Matches ¶
func (ss *SetOpExtensions) Matches(line string) bool
func (*SetOpExtensions) Parse ¶
func (ss *SetOpExtensions) Parse(lines []string) error
type SetOpParams ¶
type SetOpParams struct {
// contains filtered or unexported fields
}
func NewSetParams ¶
func NewSetParams(params []*oaispec.Parameter, setter func([]*oaispec.Parameter)) *SetOpParams
func (*SetOpParams) Matches ¶
func (s *SetOpParams) Matches(line string) bool
func (*SetOpParams) Parse ¶
func (s *SetOpParams) Parse(lines []string) error
type SetOpResponses ¶
type SetOpResponses struct {
// contains filtered or unexported fields
}
func NewSetResponses ¶
func (*SetOpResponses) Matches ¶
func (ss *SetOpResponses) Matches(line string) bool
func (*SetOpResponses) Parse ¶
func (ss *SetOpResponses) Parse(lines []string) error
type SetPattern ¶
type SetPattern struct {
// contains filtered or unexported fields
}
func NewSetPattern ¶
func NewSetPattern(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetPattern
func (*SetPattern) Matches ¶
func (sm *SetPattern) Matches(line string) bool
func (*SetPattern) Parse ¶
func (sm *SetPattern) Parse(lines []string) error
type SetReadOnlySchema ¶
type SetReadOnlySchema struct {
// contains filtered or unexported fields
}
func NewSetReadOnlySchema ¶
func NewSetReadOnlySchema(schema *oaispec.Schema) *SetReadOnlySchema
func (*SetReadOnlySchema) Matches ¶
func (su *SetReadOnlySchema) Matches(line string) bool
func (*SetReadOnlySchema) Parse ¶
func (su *SetReadOnlySchema) Parse(lines []string) error
type SetRequiredParam ¶
type SetRequiredParam struct {
// contains filtered or unexported fields
}
func NewSetRequiredParam ¶
func NewSetRequiredParam(param *oaispec.Parameter) *SetRequiredParam
func (*SetRequiredParam) Matches ¶
func (su *SetRequiredParam) Matches(line string) bool
func (*SetRequiredParam) Parse ¶
func (su *SetRequiredParam) Parse(lines []string) error
type SetRequiredSchema ¶
func NewSetRequiredSchema ¶
func NewSetRequiredSchema(schema *oaispec.Schema, field string) *SetRequiredSchema
func (*SetRequiredSchema) Matches ¶
func (su *SetRequiredSchema) Matches(line string) bool
func (*SetRequiredSchema) Parse ¶
func (su *SetRequiredSchema) Parse(lines []string) error
type SetSchemes ¶
type SetSchemes struct {
// contains filtered or unexported fields
}
func NewSetSchemes ¶
func NewSetSchemes(set func([]string)) *SetSchemes
func (*SetSchemes) Matches ¶
func (ss *SetSchemes) Matches(line string) bool
func (*SetSchemes) Parse ¶
func (ss *SetSchemes) Parse(lines []string) error
type SetSecurity ¶
type SetSecurity struct {
// contains filtered or unexported fields
}
func NewSetSecurityScheme ¶
func NewSetSecurityScheme(setter func([]map[string][]string)) *SetSecurity
func (*SetSecurity) Matches ¶
func (ss *SetSecurity) Matches(line string) bool
func (*SetSecurity) Parse ¶
func (ss *SetSecurity) Parse(lines []string) error
type SetUnique ¶
type SetUnique struct {
// contains filtered or unexported fields
}
func NewSetUnique ¶
func NewSetUnique(builder ifaces.ValidationBuilder, opts ...PrefixRxOption) *SetUnique
type TagParser ¶
type TagParser struct {
Name string
MultiLine bool
SkipCleanUp bool
Lines []string
Parser ifaces.ValueParser
}
TagParser pairs a named tag with a ifaces.ValueParser that recognizes and extracts its value from comment lines.
A TagParser operates in one of two modes:
Single-line: the tag matches exactly one line (e.g. "maximum: 10"). The SectionedParser resets its current tagger after every single-line match, so the next line is free to match a different tagger.
Multi-line: the tag's first matching line is a header (e.g. "consumes:") and all subsequent lines are collected as its body until a different tagger matches or the comment block ends. The header line itself is NOT included in Lines — only the body lines that follow it.
SkipCleanUp controls whether the SectionedParser strips comment prefixes (// , *, etc.) from the collected Lines before calling Parse. YAML-based taggers set this to true because they need the original indentation intact.
Lines is populated by the SectionedParser during its scan; after the scan completes, Parse is called with those lines to extract the value.
func NewMultiLineTagParser ¶
func NewMultiLineTagParser(name string, parser ifaces.ValueParser, skipCleanUp bool) TagParser
NewMultiLineTagParser creates a TagParser that collects all lines following the matching header until a different tag or annotation is encountered.
Example usage (from NewMetaParser):
NewMultiLineTagParser("TOS",
newMultilineDropEmptyParser(rxTOS, metaTOSSetter(info)),
false, // clean up comment prefixes before parsing
)
This creates a tagger that recognizes "Terms of Service:" and collects every subsequent line into the TOS field, stripping comment prefixes.
func NewSingleLineTagParser ¶
func NewSingleLineTagParser(name string, parser ifaces.ValueParser) TagParser
NewSingleLineTagParser creates a TagParser that matches and parses exactly one line. After the match, the SectionedParser resets its current tagger so subsequent lines can match other taggers.
Example usage (from NewMetaParser):
NewSingleLineTagParser("Version",
&setMetaSingle{Spec: swspec, Rx: rxVersion, Set: setInfoVersion},
)
This creates a tagger that recognizes "Version: 1.0.0" and writes the captured value into swspec.Info.Version.
type YAMLParser ¶
type YAMLParser struct {
// contains filtered or unexported fields
}
func NewYAMLParser ¶
func NewYAMLParser(opts ...YAMLParserOption) *YAMLParser
func (*YAMLParser) Matches ¶
func (y *YAMLParser) Matches(line string) bool
func (*YAMLParser) Parse ¶
func (y *YAMLParser) Parse(lines []string) error
type YAMLParserOption ¶
type YAMLParserOption func(*YAMLParser)
func WithExtensionMatcher ¶
func WithExtensionMatcher() YAMLParserOption
func WithMatcher ¶
func WithMatcher(rx *regexp.Regexp) YAMLParserOption
func WithSetter ¶
func WithSetter(set func(json.RawMessage) error) YAMLParserOption
type YAMLSpecScanner ¶
type YAMLSpecScanner struct {
// contains filtered or unexported fields
}
YAMLSpecScanner aggregates lines in header until it sees `---`, the beginning of a YAML spec.
func NewYAMLSpecScanner ¶
func NewYAMLSpecScanner(setTitle func([]string), setDescription func([]string)) *YAMLSpecScanner
func (*YAMLSpecScanner) Description ¶
func (sp *YAMLSpecScanner) Description() []string
func (*YAMLSpecScanner) Parse ¶
func (sp *YAMLSpecScanner) Parse(doc *ast.CommentGroup) error
func (*YAMLSpecScanner) Title ¶
func (sp *YAMLSpecScanner) Title() []string
func (*YAMLSpecScanner) UnmarshalSpec ¶
func (sp *YAMLSpecScanner) UnmarshalSpec(u func([]byte) error) (err error)
Source Files