cli

Documentation

Index

• Constants
• Variables
• func CheckDrift(path string, data []byte) error
• func CleanupDriver(driverDir string, keep bool)
• func DriverDir(cfg Config) string
• func ResolveOutputPath(cfg Config) string
• func RunDriver(driverDir string) ([]byte, string, error)
• func RunPipeline(cfg Config) ([]byte, []string, error)
• func Serve(cfg Config, serveCfg ServeConfig) error
• func WriteAtomic(path string, data []byte) error
• func WriteDriver(cfg Config, entry Entry, hook *Hook, loader *ConfigLoader) (string, error)
• type Config
  • func LoadConfig(overrides Overrides) (Config, error)
• type ConfigLoader
  • func ResolveConfigLoader(workdir, value, path string) (ConfigLoader, error)
• type DriverData
  • func BuildDriverData(cfg Config, entry Entry, hook *Hook, loader *ConfigLoader) (DriverData, error)
• type DriverError
  • func (e *DriverError) Error() string
• type Entry
  • func DiscoverEntry(workdir string, scope []string) (Entry, error)
  • func ResolveEntry(workdir, value string) (Entry, error)
• type EntryCandidate
  • func (c EntryCandidate) Symbol() string
• type EntryConfig
• type ExternalDocsConfig
• type Hook
  • func ResolveHook(workdir, value string) (Hook, error)
• type InfoConfig
• type InitOptions
• type InitResult
  • func InitConfig(opts InitOptions) (InitResult, error)
• type OAuthFlow
• type OAuthFlows
• type Overrides
• type Scheme
• type ServeConfig
• type ServerConfig
• type TagConfig

Constants

const (
	// FormatYAML emits the spec as YAML.
	FormatYAML = "yaml"
	// FormatJSON emits the spec as JSON.
	FormatJSON = "json"
)

const (
	ExitUsage       = 1
	ExitBuildFailed = 2
	ExitRunFailed   = 3
	ExitDrift       = 4
	ExitWriteFailed = 5
)

Variables

var ErrDrift = errors.New("openapi output is out of date")

Functions

func CheckDrift

func CheckDrift(path string, data []byte) error

func CleanupDriver

func CleanupDriver(driverDir string, keep bool)

func DriverDir

func DriverDir(cfg Config) string

func ResolveOutputPath

func ResolveOutputPath(cfg Config) string

func RunDriver

func RunDriver(driverDir string) ([]byte, string, error)

func RunPipeline

func RunPipeline(cfg Config) ([]byte, []string, error)

func Serve

func Serve(cfg Config, serveCfg ServeConfig) error

func WriteAtomic

func WriteAtomic(path string, data []byte) error

func WriteDriver

func WriteDriver(cfg Config, entry Entry, hook *Hook, loader *ConfigLoader) (string, error)

Types

type Config

type Config struct {
	ConfigPath       string
	ConfigExplicit   bool
	Entry            string            `yaml:"entry"`
	Out              string            `yaml:"out"`
	Format           string            `yaml:"format"`
	Sources          []string          `yaml:"sources"`
	IncludeTestFiles bool              `yaml:"includeTestFiles"`
	Info             InfoConfig        `yaml:"info"`
	Servers          []ServerConfig    `yaml:"servers"`
	Tags             []TagConfig       `yaml:"tags"`
	SecuritySchemes  map[string]Scheme `yaml:"securitySchemes"`
	MetadataHook     string            `yaml:"metadataHook"`
	EntryConfig      EntryConfig       `yaml:"entryConfig"`
	Workdir          string            `yaml:"workdir"`
	KeepDriver       bool              `yaml:"keepDriver"`
	Verbose          bool              `yaml:"verbose"`
	// EntryAutoDiscovered is true when the entry was filled in by
	// DiscoverEntry rather than the config file or CLI flags. CLI commands
	// use this to surface "entry: ..." back to the user so the auto-pick is
	// never invisible.
	EntryAutoDiscovered bool `yaml:"-"`
	// EntryDiscoveryScope narrows where DiscoverEntry looks for an entry
	// function. Filled in by the CLI from the optional positional path
	// argument. It does NOT affect Sources (comment extraction), which is
	// kept module-wide so descriptions on referenced types are not lost
	// when the entry lives in a sub-tree.
	EntryDiscoveryScope []string `yaml:"-"`
	// ResolvedEntry caches the *Entry produced by DiscoverEntry so the
	// pipeline can skip a second packages.Load on the auto-discovery path.
	// nil when the entry was set explicitly and still needs ResolveEntry.
	ResolvedEntry *Entry `yaml:"-"`
}

func LoadConfig

func LoadConfig(overrides Overrides) (Config, error)

type ConfigLoader

type ConfigLoader struct {
	ImportPath string
	FuncName   string
	Path       string
}

func ResolveConfigLoader

func ResolveConfigLoader(workdir, value, path string) (ConfigLoader, error)

type DriverData

type DriverData struct {
	Entry              Entry
	Hook               Hook
	ConfigLoader       ConfigLoader
	HasHook            bool
	HasConfigLoader    bool
	Format             string
	OptionSnippets     []string
	InfoDescription    string
	ServerDescriptions []string
	TagSnippets        []string
}

func BuildDriverData

func BuildDriverData(cfg Config, entry Entry, hook *Hook, loader *ConfigLoader) (DriverData, error)

type DriverError

type DriverError struct {
	Phase    string
	ExitCode int
	Stderr   string
	Cause    error
}

func (*DriverError) Error

func (e *DriverError) Error() string

type Entry

type Entry struct {
	ImportPath   string
	FuncName     string
	ReturnsError bool
	TakesContext bool
	TakesConfig  bool
}

func DiscoverEntry

func DiscoverEntry(workdir string, scope []string) (Entry, error)

DiscoverEntry walks the given scope (e.g. []string{"./..."}) under workdir and looks for an exported function whose signature matches one of the supported entry shapes (see entrySignatureError).

Resolution rules:

• If one or more candidates are marked with `// fox-openapi:entry`, only marked candidates are considered.
• Exactly one candidate -> success.
• Zero candidates -> "no entry function found" error.
• Multiple candidates -> error listing all symbols so the user can disambiguate via --entry or the marker comment.

func ResolveEntry

func ResolveEntry(workdir, value string) (Entry, error)

type EntryCandidate

type EntryCandidate struct {
	Entry  Entry
	Marked bool
}

EntryCandidate describes a function that matches the entry signature. It is exported so callers can render multi-match diagnostics.

func (EntryCandidate) Symbol

func (c EntryCandidate) Symbol() string

Symbol returns the fully qualified runtime symbol (importPath.FuncName).

type EntryConfig

type EntryConfig struct {
	Loader string `yaml:"loader"`
	Path   string `yaml:"path"`
}

type ExternalDocsConfig

type ExternalDocsConfig struct {
	URL         string `yaml:"url"`
	Description string `yaml:"description"`
}

type Hook

type Hook struct {
	ImportPath string
	FuncName   string
}

func ResolveHook

func ResolveHook(workdir, value string) (Hook, error)

type InfoConfig

type InfoConfig struct {
	Title       string `yaml:"title"`
	Version     string `yaml:"version"`
	Description string `yaml:"description"`
}

type InitOptions

type InitOptions struct {
	Workdir    string
	ConfigPath string
	Entry      string
	Out        string
	Title      string
	Version    string
	Force      bool
}

InitOptions configures fox-openapi.yaml initialization.

type InitResult

type InitResult struct {
	ConfigPath     string
	Entry          string
	AutoDiscovered bool
}

InitResult describes what InitConfig wrote so callers can surface it.

func InitConfig

func InitConfig(opts InitOptions) (InitResult, error)

InitConfig writes an initial fox-openapi.yaml.

type OAuthFlow

type OAuthFlow struct {
	AuthorizationURL string            `yaml:"authorizationUrl"`
	TokenURL         string            `yaml:"tokenUrl"`
	RefreshURL       string            `yaml:"refreshUrl"`
	Scopes           map[string]string `yaml:"scopes"`
}

type OAuthFlows

type OAuthFlows struct {
	Implicit          *OAuthFlow `yaml:"implicit"`
	Password          *OAuthFlow `yaml:"password"`
	ClientCredentials *OAuthFlow `yaml:"clientCredentials"`
	AuthorizationCode *OAuthFlow `yaml:"authorizationCode"`
}

type Overrides

type Overrides struct {
	ConfigPath           string
	ConfigExplicit       bool
	Entry                string
	EntrySet             bool
	Out                  string
	OutSet               bool
	Format               string
	FormatSet            bool
	InfoTitle            string
	InfoTitleSet         bool
	InfoVersion          string
	InfoVersionSet       bool
	Servers              []string
	ServersSet           bool
	Sources              []string
	SourcesSet           bool
	IncludeTestFiles     bool
	IncludeTestFilesSet  bool
	MetadataHook         string
	MetadataHookSet      bool
	EntryConfigLoader    string
	EntryConfigLoaderSet bool
	EntryConfigPath      string
	EntryConfigPathSet   bool
	Workdir              string
	WorkdirSet           bool
	KeepDriver           bool
	KeepDriverSet        bool
	Verbose              bool
	VerboseSet           bool
	// EntryDiscoveryScope is set by the CLI from the optional positional
	// path argument. It limits where DiscoverEntry searches but does not
	// affect Sources (comment extraction).
	EntryDiscoveryScope    []string
	EntryDiscoveryScopeSet bool
}

type Scheme

type Scheme struct {
	Type             string      `yaml:"type"`
	Description      string      `yaml:"description"`
	Name             string      `yaml:"name"`
	In               string      `yaml:"in"`
	Scheme           string      `yaml:"scheme"`
	BearerFormat     string      `yaml:"bearerFormat"`
	Flows            *OAuthFlows `yaml:"flows"`
	OpenIDConnectURL string      `yaml:"openIdConnectUrl"`
}

type ServeConfig

type ServeConfig struct {
	Addr  string
	UIs   []string
	Watch bool
	Open  bool
	// Stdout is where startup banners are written. Defaults to os.Stdout.
	Stdout io.Writer
}

type ServerConfig

type ServerConfig struct {
	URL         string `yaml:"url"`
	Description string `yaml:"description"`
}

type TagConfig

type TagConfig struct {
	Name         string              `yaml:"name"`
	Description  string              `yaml:"description"`
	ExternalDocs *ExternalDocsConfig `yaml:"externalDocs"`
}