sdk

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: EUPL-1.2 Imports: 9 Imported by: 0

Documentation

Overview

Package sdk provides OpenAPI SDK generation and diff capabilities.

Index

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 skips generators that are unavailable on this machine.
	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

func CloneConfig(config *Config) *Config

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

func New(projectDir string, config *Config) *SDK

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

func (s *SDK) Config() *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

func (s *SDK) Generate(ctx context.Context) core.Result

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

func (s *SDK) GenerateLanguage(ctx context.Context, lang string) core.Result

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

func (s *SDK) GenerateLanguageWithStatus(ctx context.Context, lang string) core.Result

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

func (s *SDK) GenerateWithStatus(ctx context.Context) core.Result

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

func (s *SDK) SetVersion(version string)

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

func (s *SDK) ValidateSpec(ctx context.Context) core.Result

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL