Documentation
¶
Overview ¶
Package generate provides output generation from APIStyleSpec.
This package can generate various outputs from a style specification:
- Markdown documentation (human-readable style guide)
- Spectral YAML (linting ruleset for Spectral/vacuum)
Usage:
spec, _ := profile.Load("azure")
markdown, err := generate.Markdown(spec, nil)
spectral, err := generate.Spectral(spec, nil)
The generated outputs can be written to files or served via API.
Index ¶
- func Markdown(spec *types.APIStyleSpec, opts *MarkdownOptions) (string, error)
- func Spectral(spec *types.APIStyleSpec, opts *SpectralOptions) (string, error)
- func WriteMkDocs(result *MkDocsResult, outputDir string) error
- type DirectiveExample
- type GenerationDirective
- type GenerationMetadata
- type GenerationPhase
- type GenerationRubric
- type MarkdownOptions
- type MkDocsOptions
- type MkDocsResult
- type SpectralOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Markdown ¶
func Markdown(spec *types.APIStyleSpec, opts *MarkdownOptions) (string, error)
Markdown generates Markdown documentation from an APIStyleSpec.
func Spectral ¶
func Spectral(spec *types.APIStyleSpec, opts *SpectralOptions) (string, error)
Spectral generates a Spectral-compatible YAML ruleset from an APIStyleSpec.
func WriteMkDocs ¶ added in v0.3.0
func WriteMkDocs(result *MkDocsResult, outputDir string) error
WriteMkDocs writes the MkDocs site to a directory.
Types ¶
type DirectiveExample ¶ added in v0.5.0
DirectiveExample shows good and bad patterns.
type GenerationDirective ¶ added in v0.5.0
type GenerationDirective struct {
RuleID string `json:"ruleId"`
Title string `json:"title"`
Priority int `json:"priority"`
Prompt string `json:"prompt"`
Template string `json:"template,omitempty"`
Checklist []string `json:"checklist,omitempty"`
Examples []DirectiveExample `json:"examples,omitempty"`
Required bool `json:"required"`
}
GenerationDirective is a single generation instruction.
type GenerationMetadata ¶ added in v0.5.0
type GenerationMetadata struct {
Author string `json:"author,omitempty"`
TotalRules int `json:"totalRules"`
}
GenerationMetadata contains rubric metadata.
type GenerationPhase ¶ added in v0.5.0
type GenerationPhase struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Order int `json:"order"`
Directives []GenerationDirective `json:"directives"`
}
GenerationPhase groups directives by generation phase.
type GenerationRubric ¶ added in v0.5.0
type GenerationRubric struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Version string `json:"version,omitempty"`
Phases []GenerationPhase `json:"phases"`
Metadata *GenerationMetadata `json:"metadata,omitempty"`
}
GenerationRubric contains guidance for AI agents generating OpenAPI specs.
func GenerationRubricFromSpec ¶ added in v0.5.0
func GenerationRubricFromSpec(spec *types.APIStyleSpec) *GenerationRubric
GenerationRubricFromSpec builds a generation rubric from an APIStyleSpec.
func (*GenerationRubric) ToJSON ¶ added in v0.5.0
func (r *GenerationRubric) ToJSON() ([]byte, error)
ToJSON serializes the generation rubric to JSON.
type MarkdownOptions ¶
type MarkdownOptions struct {
// IncludeTOC adds a table of contents.
IncludeTOC bool
// IncludeExamples includes good/bad examples.
IncludeExamples bool
// IncludeRationale includes rule rationales.
IncludeRationale bool
// IncludeReferences includes external references.
IncludeReferences bool
// IncludeConformance includes conformance level details.
IncludeConformance bool
// IncludeMetadata includes spec metadata.
IncludeMetadata bool
// IncludeIntroduction includes the introduction section.
IncludeIntroduction bool
// IncludePrinciples includes design principles.
IncludePrinciples bool
// IncludePatterns includes API design patterns.
IncludePatterns bool
// IncludeGlossary includes the glossary.
IncludeGlossary bool
// IncludeDescription includes rule descriptions.
IncludeDescription bool
// SeverityEmojis uses emojis for severity indicators.
SeverityEmojis bool
}
MarkdownOptions configures Markdown generation.
func DefaultMarkdownOptions ¶
func DefaultMarkdownOptions() *MarkdownOptions
DefaultMarkdownOptions returns options with all features enabled.
type MkDocsOptions ¶ added in v0.3.0
type MkDocsOptions struct {
// SiteName is the MkDocs site name.
SiteName string
// SiteURL is the base URL for the site.
SiteURL string
// RepoURL is the source repository URL.
RepoURL string
// Theme is the MkDocs theme (default: material).
Theme string
// IncludeSearch enables search functionality.
IncludeSearch bool
// SplitCategories creates separate pages per category.
SplitCategories bool
// SplitPatterns creates separate pages per pattern.
SplitPatterns bool
// MarkdownOptions for generating individual pages.
MarkdownOptions *MarkdownOptions
}
MkDocsOptions configures MkDocs site generation.
func DefaultMkDocsOptions ¶ added in v0.3.0
func DefaultMkDocsOptions() *MkDocsOptions
DefaultMkDocsOptions returns default MkDocs configuration.
type MkDocsResult ¶ added in v0.3.0
type MkDocsResult struct {
// Config is the mkdocs.yml content.
Config string
// Pages maps file paths (relative to docs/) to content.
Pages map[string]string
}
MkDocsResult contains the generated MkDocs site files.
func MkDocs ¶ added in v0.3.0
func MkDocs(spec *types.APIStyleSpec, opts *MkDocsOptions) (*MkDocsResult, error)
MkDocs generates a complete MkDocs site structure from an APIStyleSpec.
type SpectralOptions ¶
type SpectralOptions struct {
// IncludeDisabled includes disabled rules (commented out).
IncludeDisabled bool
// IncludeDescriptions adds rule descriptions as comments.
IncludeDescriptions bool
// SkipNonEnforceable skips rules without enforcement config.
SkipNonEnforceable bool
}
SpectralOptions configures Spectral ruleset generation.
func DefaultSpectralOptions ¶
func DefaultSpectralOptions() *SpectralOptions
DefaultSpectralOptions returns options with sensible defaults.
Source Files
Directories