Documentation
¶
Overview ¶
Package sdk provides OpenAPI SDK generation and diff capabilities.
Index ¶
- func Diff(basePath, revisionPath string) core.Result
- func DiffExitCode(result *DiffResult, failure any) int
- func DiffWithOptions(basePath, revisionPath string, opts DiffOptions) core.Result
- type Config
- type DiffConfig
- type DiffOptions
- type DiffResult
- type LanguageResult
- type PackageConfig
- type PublishConfig
- type SDK
- func (s *SDK) Config() *Config
- func (s *SDK) DetectSpec() core.Result
- func (s *SDK) Generate(ctx context.Context) core.Result
- func (s *SDK) GenerateLanguage(ctx context.Context, lang string) core.Result
- func (s *SDK) GenerateLanguageWithStatus(ctx context.Context, lang string) core.Result
- func (s *SDK) GenerateWithStatus(ctx context.Context) core.Result
- func (s *SDK) SetVersion(version string)
- func (s *SDK) ValidateSpec(ctx context.Context) core.Result
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Diff ¶
func Diff(basePath, revisionPath string) core.Result
Diff compares two OpenAPI specs and detects breaking changes.
result, err := sdk.Diff("docs/openapi.v1.yaml", "docs/openapi.yaml")
Example ¶
--- v0.9.0 generated usage examples ---
_ = Diff(core.Path(core.TempDir(), "go-build-compliance"), core.Path(core.TempDir(), "go-build-compliance"))
core.Println("Diff")
Output: Diff
func DiffExitCode ¶
func DiffExitCode(result *DiffResult, failure any) int
DiffExitCode returns the exit code for CI integration. 0 = no breaking changes, 1 = breaking changes, 2 = error.
os.Exit(sdk.DiffExitCode(sdk.Diff("old.yaml", "new.yaml")))
Example ¶
_ = DiffExitCode(&DiffResult{}, nil)
core.Println("DiffExitCode")
Output: DiffExitCode
func DiffWithOptions ¶
func DiffWithOptions(basePath, revisionPath string, opts DiffOptions) core.Result
DiffWithOptions compares two OpenAPI specs and includes changes at or above the requested severity level.
Example ¶
_ = DiffWithOptions(core.Path(core.TempDir(), "go-build-compliance"), core.Path(core.TempDir(), "go-build-compliance"), DiffOptions{})
core.Println("DiffWithOptions")
Output: DiffWithOptions
Types ¶
type Config ¶
type Config struct {
// Spec is the path to the OpenAPI spec file (auto-detected if empty).
Spec string `json:"spec,omitempty" yaml:"spec,omitempty"`
// Languages to generate SDKs for.
Languages []string `json:"languages,omitempty" yaml:"languages,omitempty"`
// Output directory (default: sdk/).
Output string `json:"output,omitempty" yaml:"output,omitempty"`
SkipUnavailable bool `json:"skip_unavailable,omitempty" yaml:"skip_unavailable,omitempty"`
// Package naming configuration.
Package PackageConfig `json:"package" yaml:"package,omitempty"`
// Diff configuration for breaking change detection.
Diff DiffConfig `json:"diff" yaml:"diff,omitempty"`
// Publish configuration for monorepo publishing.
Publish PublishConfig `json:"publish" yaml:"publish,omitempty"`
}
Config holds SDK generation configuration for SDK commands and releases.
cfg := &sdk.Config{Languages: []string{"typescript"}, Output: "sdk"}
func CloneConfig ¶
CloneConfig returns a deep copy of an SDK config.
Example ¶
_ = CloneConfig(&Config{})
core.Println("CloneConfig")
Output: CloneConfig
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns sensible defaults for SDK configuration.
cfg := sdk.DefaultConfig() // languages: typescript, python, go, php
Example ¶
_ = DefaultConfig()
core.Println("DefaultConfig")
Output: DefaultConfig
func (*Config) ApplyDefaults ¶
func (c *Config) ApplyDefaults()
ApplyDefaults fills in documented defaults for partial SDK configs.
Example ¶
subject := &Config{}
subject.ApplyDefaults()
core.Println("Config_ApplyDefaults")
Output: Config_ApplyDefaults
type DiffConfig ¶
type DiffConfig struct {
// Enabled determines whether to run diff checks.
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
// FailOnBreaking fails the release if breaking changes are detected.
FailOnBreaking bool `json:"fail_on_breaking,omitempty" yaml:"fail_on_breaking,omitempty"`
EnabledConfigured bool `yaml:"-" json:"-"`
}
DiffConfig holds breaking change detection configuration.
cfg.Diff = sdk.DiffConfig{Enabled: true, FailOnBreaking: true}
func (*DiffConfig) UnmarshalYAML ¶
func (c *DiffConfig) UnmarshalYAML(value *yaml.Node) core.Result
UnmarshalYAML accepts either `diff: true` or the expanded mapping form.
Example ¶
subject := &DiffConfig{}
_ = subject.UnmarshalYAML(&yaml.Node{Kind: yaml.ScalarNode, Value: "false"})
core.Println("DiffConfig_UnmarshalYAML")
Output: DiffConfig_UnmarshalYAML
type DiffOptions ¶
type DiffOptions struct {
// MinimumLevel selects the lowest severity to include.
// Defaults to checker.ERR to preserve breaking-only behaviour.
MinimumLevel checker.Level
}
DiffOptions controls the change levels included in the diff result.
type DiffResult ¶
type DiffResult struct {
// Breaking is true if breaking changes were detected.
Breaking bool
// Changes is the list of breaking changes.
Changes []string
// HasWarnings is true if warning-level changes were detected.
HasWarnings bool
// Warnings is the list of warning-level changes.
Warnings []string
// Summary is a human-readable summary.
Summary string
}
DiffResult holds the result of comparing two OpenAPI specs.
result, err := sdk.Diff("docs/openapi.v1.yaml", "docs/openapi.yaml")
type LanguageResult ¶
type LanguageResult struct {
Language string
OutputDir string
Generated bool
Skipped bool
Reason string
}
LanguageResult reports the outcome of a single SDK language generation attempt.
type PackageConfig ¶
type PackageConfig struct {
// Name is the base package name.
Name string `json:"name,omitempty" yaml:"name,omitempty"`
// Version is the SDK version (supports templates like {{.Version}}).
Version string `json:"version,omitempty" yaml:"version,omitempty"`
}
PackageConfig holds package naming configuration.
cfg.Package = sdk.PackageConfig{Name: "@host-uk/api-client", Version: "1.0.0"}
type PublishConfig ¶
type PublishConfig struct {
// Repo is the SDK monorepo (e.g., "myorg/sdks").
Repo string `json:"repo,omitempty" yaml:"repo,omitempty"`
// Path is the subdirectory for this SDK (e.g., "packages/myapi").
Path string `json:"path,omitempty" yaml:"path,omitempty"`
}
PublishConfig holds monorepo publishing configuration.
cfg.Publish = sdk.PublishConfig{Repo: "host-uk/ts", Path: "packages/api-client"}
type SDK ¶
type SDK struct {
// contains filtered or unexported fields
}
SDK orchestrates OpenAPI SDK generation.
s := sdk.New(".", cfg)
func New ¶
New creates a new SDK instance.
s := sdk.New(".", &sdk.Config{Languages: []string{"typescript"}, Output: "sdk"})
Example ¶
--- v0.9.0 generated usage examples ---
_ = New(core.Path(core.TempDir(), "go-build-compliance"), &Config{})
core.Println("New")
Output: New
func (*SDK) Config ¶
Config returns a copy of the SDK's resolved runtime configuration.
Example ¶
subject := &SDK{}
_ = subject.Config()
core.Println("SDK_Config")
Output: SDK_Config
func (*SDK) DetectSpec ¶
func (s *SDK) DetectSpec() core.Result
DetectSpec finds the OpenAPI spec file. Priority: config path -> common paths -> Laravel Scramble.
path, err := s.DetectSpec() // → "api/openapi.yaml", nil
Example ¶
--- v0.9.0 generated usage examples ---
subject := &SDK{}
_ = subject.DetectSpec()
core.Println("SDK_DetectSpec")
Output: SDK_DetectSpec
func (*SDK) Generate ¶
Generate generates SDKs for all configured languages.
err := s.Generate(ctx) // generates sdk/typescript/, sdk/python/, etc.
Example ¶
ctx, cancel := core.WithCancel(core.Background())
cancel()
subject := &SDK{}
_ = subject.Generate(ctx)
core.Println("SDK_Generate")
Output: SDK_Generate
func (*SDK) GenerateLanguage ¶
GenerateLanguage generates SDK for a specific language.
err := s.GenerateLanguage(ctx, "typescript") // generates sdk/typescript/
Example ¶
ctx, cancel := core.WithCancel(core.Background())
cancel()
subject := &SDK{}
_ = subject.GenerateLanguage(ctx, "go")
core.Println("SDK_GenerateLanguage")
Output: SDK_GenerateLanguage
func (*SDK) GenerateLanguageWithStatus ¶
GenerateLanguageWithStatus generates SDK for a specific language and reports whether it was generated or skipped.
Example ¶
ctx, cancel := core.WithCancel(core.Background())
cancel()
subject := &SDK{}
_ = subject.GenerateLanguageWithStatus(ctx, "go")
core.Println("SDK_GenerateLanguageWithStatus")
Output: SDK_GenerateLanguageWithStatus
func (*SDK) GenerateWithStatus ¶
GenerateWithStatus generates SDKs for all configured languages and returns per-language status information.
Example ¶
ctx, cancel := core.WithCancel(core.Background())
cancel()
subject := &SDK{}
_ = subject.GenerateWithStatus(ctx)
core.Println("SDK_GenerateWithStatus")
Output: SDK_GenerateWithStatus
func (*SDK) SetVersion ¶
SetVersion sets the SDK version for generation. This updates both the internal version field and the config's Package.Version.
s.SetVersion("v1.2.3")
Example ¶
subject := &SDK{}
subject.SetVersion("v1.2.3")
core.Println("SDK_SetVersion")
Output: SDK_SetVersion
func (*SDK) ValidateSpec ¶
ValidateSpec detects and validates the OpenAPI specification for this SDK.
detectedPath, err := s.ValidateSpec(context.Background())
Example ¶
--- v0.9.0 generated usage examples ---
ctx, cancel := core.WithCancel(core.Background())
cancel()
subject := &SDK{}
_ = subject.ValidateSpec(ctx)
core.Println("SDK_ValidateSpec")
Output: SDK_ValidateSpec
Directories
¶
| Path | Synopsis |
|---|---|
|
Package generators provides SDK code generators for different languages.
|
Package generators provides SDK code generators for different languages. |