docs: add SDK generation design (S3.4)
Design document for OpenAPI SDK generation feature: - Hybrid generators (native + openapi-generator fallback) - Core 4 languages: TypeScript, Python, Go, PHP - Auto-detection: config → common paths → Laravel Scramble - Breaking change detection with oasdiff - Monorepo publish support Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
4ae16dc09e
commit
53b3d2613d
1 changed files with 291 additions and 0 deletions
291
docs/plans/2026-01-29-sdk-generation-design.md
Normal file
291
docs/plans/2026-01-29-sdk-generation-design.md
Normal file
|
|
@ -0,0 +1,291 @@
|
||||||
|
# SDK Generation Design
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Generate typed API clients from OpenAPI specs for TypeScript, Python, Go, and PHP. Includes breaking change detection via semantic diff.
|
||||||
|
|
||||||
|
## Design Decisions
|
||||||
|
|
||||||
|
- **Generator approach**: Hybrid - native generators where available, openapi-generator fallback
|
||||||
|
- **Languages**: TypeScript, Python, Go, PHP (Core 4)
|
||||||
|
- **Detection**: Config → common paths → Laravel Scramble
|
||||||
|
- **Output**: Local `sdk/` + optional monorepo publish
|
||||||
|
- **Diff**: Semantic with oasdiff, CI-friendly exit codes
|
||||||
|
- **Priority**: DX (developer experience)
|
||||||
|
|
||||||
|
## Package Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
pkg/sdk/
|
||||||
|
├── sdk.go # Main SDK type, orchestration
|
||||||
|
├── detect.go # OpenAPI spec detection
|
||||||
|
├── diff.go # Breaking change detection (oasdiff)
|
||||||
|
├── generators/
|
||||||
|
│ ├── generator.go # Generator interface
|
||||||
|
│ ├── typescript.go # openapi-typescript-codegen
|
||||||
|
│ ├── python.go # openapi-python-client
|
||||||
|
│ ├── go.go # oapi-codegen
|
||||||
|
│ └── php.go # openapi-generator (Docker)
|
||||||
|
└── templates/ # Package scaffolding templates
|
||||||
|
├── typescript/
|
||||||
|
│ └── package.json.tmpl
|
||||||
|
├── python/
|
||||||
|
│ └── setup.py.tmpl
|
||||||
|
├── go/
|
||||||
|
│ └── go.mod.tmpl
|
||||||
|
└── php/
|
||||||
|
└── composer.json.tmpl
|
||||||
|
```
|
||||||
|
|
||||||
|
## OpenAPI Detection Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Check config: sdk.spec in .core/release.yaml
|
||||||
|
↓ not found
|
||||||
|
2. Check common paths:
|
||||||
|
- api/openapi.yaml
|
||||||
|
- api/openapi.json
|
||||||
|
- openapi.yaml
|
||||||
|
- openapi.json
|
||||||
|
- docs/api.yaml
|
||||||
|
- swagger.yaml
|
||||||
|
↓ not found
|
||||||
|
3. Laravel Scramble detection:
|
||||||
|
- Check for scramble/scramble in composer.json
|
||||||
|
- Run: php artisan scramble:export --path=api/openapi.json
|
||||||
|
- Use generated spec
|
||||||
|
↓ not found
|
||||||
|
4. Error: No OpenAPI spec found
|
||||||
|
```
|
||||||
|
|
||||||
|
## Generator Interface
|
||||||
|
|
||||||
|
```go
|
||||||
|
type Generator interface {
|
||||||
|
// Language returns the generator's target language
|
||||||
|
Language() string
|
||||||
|
|
||||||
|
// Generate creates SDK from OpenAPI spec
|
||||||
|
Generate(ctx context.Context, opts GenerateOptions) error
|
||||||
|
|
||||||
|
// Available checks if generator dependencies are installed
|
||||||
|
Available() bool
|
||||||
|
|
||||||
|
// Install provides installation instructions
|
||||||
|
Install() string
|
||||||
|
}
|
||||||
|
|
||||||
|
type GenerateOptions struct {
|
||||||
|
SpecPath string // OpenAPI spec file
|
||||||
|
OutputDir string // Where to write SDK
|
||||||
|
PackageName string // Package/module name
|
||||||
|
Version string // SDK version
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Native Generators
|
||||||
|
|
||||||
|
| Language | Tool | Install |
|
||||||
|
|------------|----------------------------|--------------------------------|
|
||||||
|
| TypeScript | openapi-typescript-codegen | `npm i -g openapi-typescript-codegen` |
|
||||||
|
| Python | openapi-python-client | `pip install openapi-python-client` |
|
||||||
|
| Go | oapi-codegen | `go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest` |
|
||||||
|
| PHP | openapi-generator (Docker) | Requires Docker |
|
||||||
|
|
||||||
|
### Fallback Strategy
|
||||||
|
|
||||||
|
```go
|
||||||
|
func (g *TypeScriptGenerator) Generate(ctx context.Context, opts GenerateOptions) error {
|
||||||
|
if g.Available() {
|
||||||
|
return g.generateNative(ctx, opts)
|
||||||
|
}
|
||||||
|
return g.generateDocker(ctx, opts) // openapi-generator in Docker
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Breaking Change Detection
|
||||||
|
|
||||||
|
Using [oasdiff](https://github.com/Tufin/oasdiff) for semantic OpenAPI comparison:
|
||||||
|
|
||||||
|
```go
|
||||||
|
import "github.com/tufin/oasdiff/diff"
|
||||||
|
import "github.com/tufin/oasdiff/checker"
|
||||||
|
|
||||||
|
func (s *SDK) Diff(base, revision string) (*DiffResult, error) {
|
||||||
|
// Load specs
|
||||||
|
baseSpec, _ := load.From(loader, base)
|
||||||
|
revSpec, _ := load.From(loader, revision)
|
||||||
|
|
||||||
|
// Compute diff
|
||||||
|
d, _ := diff.Get(diff.NewConfig(), baseSpec, revSpec)
|
||||||
|
|
||||||
|
// Check for breaking changes
|
||||||
|
breaks := checker.CheckBackwardCompatibility(
|
||||||
|
checker.GetDefaultChecks(),
|
||||||
|
d,
|
||||||
|
baseSpec,
|
||||||
|
revSpec,
|
||||||
|
)
|
||||||
|
|
||||||
|
return &DiffResult{
|
||||||
|
Breaking: len(breaks) > 0,
|
||||||
|
Changes: breaks,
|
||||||
|
Summary: formatSummary(d),
|
||||||
|
}, nil
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exit Codes for CI
|
||||||
|
|
||||||
|
| Exit Code | Meaning |
|
||||||
|
|-----------|---------|
|
||||||
|
| 0 | No breaking changes |
|
||||||
|
| 1 | Breaking changes detected |
|
||||||
|
| 2 | Error (invalid spec, etc.) |
|
||||||
|
|
||||||
|
### Breaking Change Categories
|
||||||
|
|
||||||
|
- Removed endpoints
|
||||||
|
- Changed required parameters
|
||||||
|
- Modified response schemas
|
||||||
|
- Changed authentication requirements
|
||||||
|
|
||||||
|
## CLI Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Generate SDKs from OpenAPI spec
|
||||||
|
core sdk generate # Uses .core/release.yaml config
|
||||||
|
core sdk generate --spec api.yaml # Explicit spec file
|
||||||
|
core sdk generate --lang typescript # Single language
|
||||||
|
|
||||||
|
# Check for breaking changes
|
||||||
|
core sdk diff # Compare current vs last release
|
||||||
|
core sdk diff --spec api.yaml --base v1.0.0
|
||||||
|
|
||||||
|
# Validate spec before generation
|
||||||
|
core sdk validate
|
||||||
|
core sdk validate --spec api.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
## Config Schema
|
||||||
|
|
||||||
|
In `.core/release.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
sdk:
|
||||||
|
# OpenAPI spec source (auto-detected if omitted)
|
||||||
|
spec: api/openapi.yaml
|
||||||
|
|
||||||
|
# Languages to generate
|
||||||
|
languages:
|
||||||
|
- typescript
|
||||||
|
- python
|
||||||
|
- go
|
||||||
|
- php
|
||||||
|
|
||||||
|
# Output directory (default: sdk/)
|
||||||
|
output: sdk/
|
||||||
|
|
||||||
|
# Package naming
|
||||||
|
package:
|
||||||
|
name: myapi # Base name
|
||||||
|
version: "{{.Version}}"
|
||||||
|
|
||||||
|
# Breaking change detection
|
||||||
|
diff:
|
||||||
|
enabled: true
|
||||||
|
fail_on_breaking: true # CI fails on breaking changes
|
||||||
|
|
||||||
|
# Optional: publish to monorepo
|
||||||
|
publish:
|
||||||
|
repo: myorg/sdks
|
||||||
|
path: packages/myapi
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output Structure
|
||||||
|
|
||||||
|
Each generator outputs to `sdk/{lang}/`:
|
||||||
|
|
||||||
|
```
|
||||||
|
sdk/
|
||||||
|
├── typescript/
|
||||||
|
│ ├── package.json
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── index.ts
|
||||||
|
│ │ ├── client.ts
|
||||||
|
│ │ └── models/
|
||||||
|
│ └── tsconfig.json
|
||||||
|
├── python/
|
||||||
|
│ ├── setup.py
|
||||||
|
│ ├── myapi/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── client.py
|
||||||
|
│ │ └── models/
|
||||||
|
│ └── requirements.txt
|
||||||
|
├── go/
|
||||||
|
│ ├── go.mod
|
||||||
|
│ ├── client.go
|
||||||
|
│ └── models.go
|
||||||
|
└── php/
|
||||||
|
├── composer.json
|
||||||
|
├── src/
|
||||||
|
│ ├── Client.php
|
||||||
|
│ └── Models/
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Publishing Workflow
|
||||||
|
|
||||||
|
SDK publishing integrates with the existing release pipeline:
|
||||||
|
|
||||||
|
```
|
||||||
|
core release
|
||||||
|
→ build artifacts
|
||||||
|
→ generate SDKs (if sdk: configured)
|
||||||
|
→ run diff check (warns or fails on breaking)
|
||||||
|
→ publish to GitHub release
|
||||||
|
→ publish SDKs (optional)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Monorepo Publishing
|
||||||
|
|
||||||
|
For projects using a shared SDK monorepo:
|
||||||
|
|
||||||
|
1. Clone target repo (shallow)
|
||||||
|
2. Update `packages/{name}/{lang}/`
|
||||||
|
3. Commit with version tag
|
||||||
|
4. Push (triggers downstream CI)
|
||||||
|
|
||||||
|
The SDK tarball is also attached to GitHub releases for direct download.
|
||||||
|
|
||||||
|
## Implementation Steps
|
||||||
|
|
||||||
|
1. Create `pkg/sdk/` package structure
|
||||||
|
2. Implement OpenAPI detection (`detect.go`)
|
||||||
|
3. Define Generator interface (`generators/generator.go`)
|
||||||
|
4. Implement TypeScript generator (native + fallback)
|
||||||
|
5. Implement Python generator (native + fallback)
|
||||||
|
6. Implement Go generator (native)
|
||||||
|
7. Implement PHP generator (Docker-based)
|
||||||
|
8. Add package templates (`templates/`)
|
||||||
|
9. Implement diff with oasdiff (`diff.go`)
|
||||||
|
10. Add CLI commands (`cmd/core/sdk.go`)
|
||||||
|
11. Integrate with release pipeline
|
||||||
|
12. Add monorepo publish support
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
```go
|
||||||
|
// go.mod additions
|
||||||
|
require (
|
||||||
|
github.com/tufin/oasdiff v1.x.x
|
||||||
|
github.com/getkin/kin-openapi v0.x.x
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- Unit tests for each generator
|
||||||
|
- Integration tests with sample OpenAPI specs
|
||||||
|
- Diff tests with known breaking/non-breaking changes
|
||||||
|
- E2E test generating SDKs for a real API
|
||||||
Loading…
Add table
Reference in a new issue