From 766ae8f2b73d00a52abaa09eb0d2ff54123f76d6 Mon Sep 17 00:00:00 2001 From: adelnizamutdinov Date: Fri, 16 Oct 2026 23:02:05 +0000 Subject: [PATCH] Default JSON models to HTTP compatibility and add strict config mode --- .github/workflows/ci.yaml | 3 + README.md | 29 ++++++- internal/cli/cli.go | 23 ++--- internal/cli/cli_test.go | 4 +- internal/dartemit/dartemit.go | 8 +- internal/dartemit/models.go | 2 +- internal/goemit/goemit.go | 28 ++++-- internal/goemit/templates/models.go.gotmpl | 14 ++- internal/rustemit/rustemit.go | 12 ++- internal/tsemit/strict.go | 86 +++++++++++++++++++ internal/tsemit/templates/api.ts.gotmpl | 3 +- .../tsemit/templates/strict-json.ts.gotmpl | 74 ++++++++++++++++ internal/tsemit/tsemit.go | 37 ++++++-- moon.yml | 2 +- oasmith_test.go | 62 +++++++++++++ testdata/fixtures/json-policy-cases.json | 7 ++ testdata/fixtures/json-policy.yaml | 51 +++++++++++ testdata/fixtures/rust-models.yaml | 1 + testdata/fixtures/rust-responses.yaml | 42 +++++++++ testdata/json-policy/dart-check.dart | 25 ++++++ testdata/json-policy/go-test.txt | 30 +++++++ testdata/rust-client/src/lib.rs | 42 +++++++++ 22 files changed, 548 insertions(+), 37 deletions(-) create mode 100644 internal/tsemit/strict.go create mode 100644 internal/tsemit/templates/strict-json.ts.gotmpl create mode 100644 testdata/fixtures/json-policy-cases.json create mode 100644 testdata/fixtures/json-policy.yaml create mode 100644 testdata/json-policy/dart-check.dart create mode 100644 testdata/json-policy/go-test.txt diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 25683e6..b01d754 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -22,6 +22,9 @@ jobs: with: go-version-file: go.mod cache: false + - uses: dart-lang/setup-dart@v1 + with: + sdk: '3.13.4' - name: Restore Go modules, compiler, and linter caches id: go-cache uses: actions/cache@v6 diff --git a/README.md b/README.md index 1c65daf..d93dc8f 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ surface of a general-purpose OpenAPI generator. | `types` | `go` | Go models | | `client` | `go` | Go models and HTTP client | | `client` | `typescript` | TypeScript types and HTTP client | +| `types` | `typescript` | TypeScript types | | `types` | `rust` | Serde models in `mod.rs` | | `client` | `rust` | Serde models and a Reqwest client in `mod.rs` | | `types` | `dart` | Dart JSON models in `models.dart` | @@ -43,12 +44,31 @@ Every invocation requires: - `--openapi`: input OpenAPI YAML or JSON document; - `--mode`: `types` or `client`; -- `--lang`: `go`, `typescript`, `rust`, or `dart`, subject to the supported pairs above; +- `--lang`: `go`, `typescript`, `rust`, or `dart`; - `--out`: generated output directory. JSON input is supported alongside YAML. The document syntax is accepted directly, so `.json` and `.yaml` file names work with the same command. +Generated JSON models default to HTTP compatibility: extra object fields do not +break decoding when a server adds response data. For configuration, add `--strict` +to reject unknown fields in objects declared with `additionalProperties: false`, +including nested objects, array items and tagged union payloads. Explicitly open +objects remain open. The flag applies to every language in both generation modes; +it is independent of emitting HTTP operations. It controls unknown-field handling, +not full JSON Schema validation. + +```sh +oasmith --openapi public.yaml --mode client --lang rust --out src/api +oasmith --openapi config.yaml --mode types --lang rust --strict --out src/config +``` + +Strict Go models enforce this through `UnmarshalJSON`; Rust uses Serde; Dart +uses `fromJson`. Strict TypeScript output exports `decode(value)` for +configuration and validates ordinary JSON responses in generated HTTP operations. +TypeScript interfaces alone cannot validate parsed JSON; use the generated decoder +when loading configuration. + TypeScript output is written directly from the embedded templates without external tools. @@ -224,6 +244,13 @@ Use `--mode client --lang rust --out src/api`, then `mod api;`. Add `serde` 1 (with `json`) to Cargo dependencies. Choose the Reqwest TLS features appropriate to your application. +Rust JSON models ignore unknown object fields by default, including nested +objects and tagged union payloads. This lets an older HTTP client read responses +after an API adds fields. Required fields, field types, enum values and +discriminator values still have to match the generated contract. + +For configuration, add `--strict` as described above. + Construct `api::Client::new(http, base_url, bearer_token)` with your configured `reqwest_middleware::ClientWithMiddleware`. For a client without middleware, construct it with `reqwest_middleware::ClientBuilder::new(http).build()`. diff --git a/internal/cli/cli.go b/internal/cli/cli.go index 93d898e..4c9f0e3 100644 --- a/internal/cli/cli.go +++ b/internal/cli/cli.go @@ -18,6 +18,7 @@ type Options struct { Mode string Lang string Out string + Strict bool } // Run parses args, loads the OpenAPI document, and emits requested outputs. @@ -32,17 +33,17 @@ func Run(args []string) error { } switch { case opts.Lang == "dart": - return dartemit.Emit(doc, dartemit.Options{OutDir: opts.Out}, opts.Mode == "client") + return dartemit.Emit(doc, dartemit.Options{OutDir: opts.Out, Strict: opts.Strict}, opts.Mode == "client") case opts.Lang == "rust": - return rustemit.Emit(doc, rustemit.Options{OutDir: opts.Out}, opts.Mode == "client") + return rustemit.Emit(doc, rustemit.Options{OutDir: opts.Out, StrictJSON: opts.Strict}, opts.Mode == "client") case opts.Mode == "types" && opts.Lang == "go": - return goemit.Emit(doc, goemit.Options{OutDir: opts.Out, SourcePath: opts.OpenAPI}) + return goemit.Emit(doc, goemit.Options{OutDir: opts.Out, SourcePath: opts.OpenAPI, Strict: opts.Strict}) case opts.Mode == "client" && opts.Lang == "go": - return goemit.EmitClient(doc, goemit.Options{OutDir: opts.Out, SourcePath: opts.OpenAPI}) - case opts.Mode == "client" && opts.Lang == "typescript": - return tsemit.Emit(doc, tsemit.Options{OutDir: opts.Out}) + return goemit.EmitClient(doc, goemit.Options{OutDir: opts.Out, SourcePath: opts.OpenAPI, Strict: opts.Strict}) + case opts.Lang == "typescript": + return tsemit.Emit(doc, tsemit.Options{OutDir: opts.Out, Strict: opts.Strict, TypesOnly: opts.Mode == "types"}) default: - return fmt.Errorf("unsupported --mode/--lang pair %q/%q; valid pairs are types/go, client/go, client/typescript, types/rust, client/rust, types/dart, and client/dart", opts.Mode, opts.Lang) + return fmt.Errorf("unsupported --mode/--lang pair %q/%q; valid modes are types and client; valid languages are go, typescript, rust, and dart", opts.Mode, opts.Lang) } } @@ -54,16 +55,16 @@ func Parse(args []string) (Options, error) { fs.StringVar(&opts.Mode, "mode", "", "generation mode") fs.StringVar(&opts.Lang, "lang", "", "output language") fs.StringVar(&opts.Out, "out", "", "output directory") + fs.BoolVar(&opts.Strict, "strict", false, "reject unknown JSON object fields where additionalProperties is false (for configuration)") if err := fs.Parse(args); err != nil { return Options{}, fmt.Errorf("usage: oasmith --openapi --mode --lang --out ") } if opts.OpenAPI == "" || opts.Mode == "" || opts.Lang == "" || opts.Out == "" { return Options{}, fmt.Errorf("usage: oasmith --openapi --mode --lang --out ") } - if ((opts.Mode == "types" || opts.Mode == "client") && (opts.Lang == "rust" || opts.Lang == "dart")) || - (opts.Mode == "types" && opts.Lang == "go") || - (opts.Mode == "client" && (opts.Lang == "go" || opts.Lang == "typescript")) { + if (opts.Mode == "types" || opts.Mode == "client") && + (opts.Lang == "rust" || opts.Lang == "dart" || opts.Lang == "go" || opts.Lang == "typescript") { return opts, nil } - return Options{}, fmt.Errorf("unsupported --mode/--lang pair %q/%q; valid pairs are types/go, client/go, client/typescript, types/rust, client/rust, types/dart, and client/dart", opts.Mode, opts.Lang) + return Options{}, fmt.Errorf("unsupported --mode/--lang pair %q/%q; valid modes are types and client; valid languages are go, typescript, rust, and dart", opts.Mode, opts.Lang) } diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go index 02d570c..a1d9203 100644 --- a/internal/cli/cli_test.go +++ b/internal/cli/cli_test.go @@ -24,14 +24,14 @@ func TestParseRejectsInvalidModeLangPair(t *testing.T) { _, err := cli.Parse([]string{ "--openapi", "doc.yaml", - "--mode", "types", + "--mode", "invalid", "--lang", "typescript", "--out", "out", }) if err == nil { t.Fatal("Parse invalid mode/lang succeeded") } - if !strings.Contains(err.Error(), "valid pairs are types/go, client/go, client/typescript, types/rust, client/rust, types/dart, and client/dart") { + if !strings.Contains(err.Error(), "valid modes are types and client; valid languages are go, typescript, rust, and dart") { t.Fatalf("Parse error = %q, want valid pair message", err.Error()) } } diff --git a/internal/dartemit/dartemit.go b/internal/dartemit/dartemit.go index 2b5b0a4..34fbaeb 100644 --- a/internal/dartemit/dartemit.go +++ b/internal/dartemit/dartemit.go @@ -16,19 +16,23 @@ import ( ) // Options configures Dart output emission. -type Options struct{ OutDir string } +type Options struct { + OutDir string + Strict bool +} type emitter struct { doc *openapi.Document names map[*openapi.Schema]string definitions map[string]*openapi.Schema implemented map[string][]string + strict bool err error } // Emit writes Dart models and, in client mode, operation methods for doc. func Emit(doc *openapi.Document, opts Options, client bool) error { - e := &emitter{doc: doc, names: map[*openapi.Schema]string{}, definitions: map[string]*openapi.Schema{}, implemented: map[string][]string{}} + e := &emitter{doc: doc, names: map[*openapi.Schema]string{}, definitions: map[string]*openapi.Schema{}, implemented: map[string][]string{}, strict: opts.Strict} for _, name := range doc.SchemaNames() { if name == "string" || name == "String" { continue diff --git a/internal/dartemit/models.go b/internal/dartemit/models.go index 5997df2..cc63cf2 100644 --- a/internal/dartemit/models.go +++ b/internal/dartemit/models.go @@ -127,7 +127,7 @@ func (e *emitter) writeObject(out *strings.Builder, name string, schema *openapi } out.WriteString("});\n") fmt.Fprintf(out, " factory %s.fromJson(Object? raw) {\n final map = expectPublicMap(raw);\n", name) - if strict, ok := schema.AdditionalProperties.(bool); ok && !strict { + if allowed, ok := schema.AdditionalProperties.(bool); e.strict && ok && !allowed { out.WriteString(" for (final key in map.keys) {\n if (!const {") for _, key := range keys { fmt.Fprintf(out, "%s,", quote(key)) diff --git a/internal/goemit/goemit.go b/internal/goemit/goemit.go index 3e105c9..0ae67f0 100644 --- a/internal/goemit/goemit.go +++ b/internal/goemit/goemit.go @@ -19,9 +19,10 @@ import ( type Options struct { OutDir string SourcePath string + Strict bool } -type emitter struct{} +type emitter struct{ strict bool } //go:embed templates/*.gotmpl var templateFS embed.FS @@ -31,7 +32,7 @@ func Emit(doc *openapi.Document, opts Options) error { if err := os.MkdirAll(opts.OutDir, 0o755); err != nil { return fmt.Errorf("create go output directory %q: %w", opts.OutDir, err) } - raw, err := executeTemplate("models.go", goModelsTemplateData(doc, opts.SourcePath)) + raw, err := executeTemplate("models.go", goModelsTemplateData(doc, opts)) if err != nil { return err } @@ -128,6 +129,7 @@ type goEnumValueData struct { type goObjectData struct { TypeName string Fields []goFieldData + Strict bool } type goFieldData struct { @@ -155,11 +157,11 @@ type goOneOfMappingData struct { FieldName string } -func goModelsTemplateData(doc *openapi.Document, sourcePath string) goModelsData { - e := emitter{} +func goModelsTemplateData(doc *openapi.Document, opts Options) goModelsData { + e := emitter{strict: opts.Strict} data := goModelsData{ - PackageName: packageName(doc, sourcePath), - Imports: goImports(doc), + PackageName: packageName(doc, opts.SourcePath), + Imports: goImports(doc, opts.Strict), NeedsDurationHelpers: needsDurationHelpers(doc), } for _, name := range doc.SchemaNames() { @@ -225,6 +227,9 @@ func (e *emitter) objectTemplateData(name string, schema *openapi.Schema) *goObj data := goObjectData{ TypeName: typeName, } + if allowed, ok := schema.AdditionalProperties.(bool); e.strict && ok && !allowed { + data.Strict = true + } for _, propName := range keys { prop := schema.Properties[propName] goType := e.goType(prop) @@ -330,8 +335,17 @@ func needsJSONHelpers(doc *openapi.Document) bool { return false } -func goImports(doc *openapi.Document) []string { +func goImports(doc *openapi.Document, strict bool) []string { imports := map[string]bool{} + if strict { + for _, schema := range doc.Components.Schemas { + if allowed, ok := schema.AdditionalProperties.(bool); schema.IsObject() && ok && !allowed { + imports["bytes"] = true + imports["encoding/json"] = true + imports["fmt"] = true + } + } + } if needsJSONHelpers(doc) { imports["encoding/json"] = true imports["fmt"] = true diff --git a/internal/goemit/templates/models.go.gotmpl b/internal/goemit/templates/models.go.gotmpl index b4b6d31..bc8e915 100644 --- a/internal/goemit/templates/models.go.gotmpl +++ b/internal/goemit/templates/models.go.gotmpl @@ -26,7 +26,19 @@ const ( {{define "object"}}type {{.TypeName}} struct { {{range .Fields}} {{.Name}} {{.Type}} `json:"{{.JSONName}}{{.JSONOmit}}"` {{end}}} -{{end}} +{{if .Strict}} +func (dst *{{.TypeName}}) UnmarshalJSON(data []byte) error { + type wire {{.TypeName}} + var decoded wire + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(&decoded); err != nil { + return fmt.Errorf("decode {{.TypeName}}: %w", err) + } + *dst = {{.TypeName}}(decoded) + return nil +} +{{end}}{{end}} {{define "one_of"}}// {{.TypeName}} is generated from an OpenAPI oneOf schema. {{range .Refs}}// oneOf variant: {{.TypeName}} diff --git a/internal/rustemit/rustemit.go b/internal/rustemit/rustemit.go index ceb6361..85e721d 100644 --- a/internal/rustemit/rustemit.go +++ b/internal/rustemit/rustemit.go @@ -16,18 +16,22 @@ import ( ) // Options configures Rust source emission. -type Options struct{ OutDir string } +type Options struct { + OutDir string + StrictJSON bool +} type emitter struct { schemas map[string]*openapi.Schema definitions map[string]string serdeModels bool + strictJSON bool err error } // Emit writes Rust serde models, optionally including a reqwest client. func Emit(doc *openapi.Document, opts Options, client bool) error { - e := &emitter{schemas: doc.Components.Schemas, definitions: map[string]string{}} + e := &emitter{schemas: doc.Components.Schemas, definitions: map[string]string{}, strictJSON: opts.StrictJSON} for _, name := range doc.SchemaNames() { e.define(typeName(name), doc.Components.Schemas[name]) } @@ -235,7 +239,7 @@ func (e *emitter) taggedUnion(out *strings.Builder, name string, schema *openapi variants = append(variants, variant{value, variantName, resolved}) } } - strict := true + strict := e.strictJSON for _, item := range variants { allowed, ok := item.schema.AdditionalProperties.(bool) strict = strict && ok && !allowed @@ -313,7 +317,7 @@ func (e *emitter) fields(out *strings.Builder, name string, schema *openapi.Sche func (e *emitter) object(out *strings.Builder, name string, schema *openapi.Schema) { e.serdeModels = true out.WriteString("#[derive(Clone, Debug, Serialize, Deserialize)]\n") - if allowed, ok := schema.AdditionalProperties.(bool); ok && !allowed { + if allowed, ok := schema.AdditionalProperties.(bool); e.strictJSON && ok && !allowed { out.WriteString("#[serde(deny_unknown_fields)]\n") } out.WriteString("pub struct " + name + " {\n") diff --git a/internal/tsemit/strict.go b/internal/tsemit/strict.go new file mode 100644 index 0000000..14c146b --- /dev/null +++ b/internal/tsemit/strict.go @@ -0,0 +1,86 @@ +package tsemit + +import ( + "encoding/json" + "fmt" + + "github.com/responsibleapi/oasmith/internal/openapi" +) + +func jsonShape(schema *openapi.Schema) map[string]any { + shape := map[string]any{} + if schema == nil { + return shape + } + if schema.Ref != "" { + shape["ref"] = openapi.RefName(schema.Ref) + return shape + } + if len(schema.Type) > 0 { + shape["type"] = schema.Type + } + if schema.Const != nil { + shape["const"] = schema.Const + } + if len(schema.Enum) > 0 { + shape["enum"] = schema.Enum + } + if schema.AdditionalProperties != nil { + shape["additionalProperties"] = schema.AdditionalProperties + } + if len(schema.Properties) > 0 { + properties := map[string]any{} + for key, property := range schema.Properties { + properties[key] = jsonShape(property) + } + shape["properties"] = properties + } + if len(schema.Required) > 0 { + shape["required"] = schema.Required + } + if schema.Items != nil { + shape["items"] = jsonShape(schema.Items) + } + if len(schema.OneOf) > 0 { + variants := []any{} + for _, variant := range schema.OneOf { + variants = append(variants, jsonShape(variant)) + } + shape["oneOf"] = variants + } + if schema.Discriminator != nil { + mapping := map[string]string{} + for tag, ref := range schema.Discriminator.Mapping { + mapping[tag] = openapi.RefName(ref) + } + shape["discriminator"] = map[string]any{"propertyName": schema.Discriminator.PropertyName, "mapping": mapping} + } + return shape +} + +func jsonSchemaSource(schema *openapi.Schema) (string, error) { + raw, err := json.Marshal(jsonShape(schema)) + if err != nil { + return "", fmt.Errorf("encode TypeScript JSON schema: %w", err) + } + return string(raw), nil +} + +func strictJSONSource(doc *openapi.Document) (string, error) { + schemas := map[string]any{} + for _, name := range doc.SchemaNames() { + schema := doc.Components.Schemas[name] + if payload := doc.SSEPayloadSchema(name); payload != nil { + schema = payload + } + schemas[name] = jsonShape(schema) + } + raw, err := json.Marshal(schemas) + if err != nil { + return "", fmt.Errorf("encode TypeScript JSON schemas: %w", err) + } + return executeTemplate("strict-json.ts", struct { + SchemasJSON string + Models []modelData + }{string(raw), modelsTemplateData(doc).Schemas}) +} diff --git a/internal/tsemit/templates/api.ts.gotmpl b/internal/tsemit/templates/api.ts.gotmpl index 3262ae9..3972ec3 100644 --- a/internal/tsemit/templates/api.ts.gotmpl +++ b/internal/tsemit/templates/api.ts.gotmpl @@ -1,6 +1,7 @@ {{define "api.ts"}}{{if .Imports}}import type { {{range .Imports}} {{.}}, {{end}}} from './types.ts'; +{{end}}{{if .Strict}}import { decodeJSON } from './types.ts'; {{end}} export type FetchInterceptor = (chain: FetchInterceptorChain) => Promise; @@ -738,7 +739,7 @@ async function runInterceptors( ); keepSSE = true; return { status: {{.Status}}, body: parseEventStream<{{.Type}}>(raw, undefined), raw }; -{{else if .JSON}} const body: {{.Type}} = await response.json(); +{{else if .JSON}} const body: {{.Type}} = {{if .Schema}}decodeJSON(await response.json(), {{.Schema}}) as {{.Type}}{{else}}await response.json(){{end}}; return { status: {{.Status}}, body, raw: response }; {{else if .Text}} const body: {{.Type}} = await response.text(); return { status: {{.Status}}, body, raw: response }; diff --git a/internal/tsemit/templates/strict-json.ts.gotmpl b/internal/tsemit/templates/strict-json.ts.gotmpl new file mode 100644 index 0000000..88d4627 --- /dev/null +++ b/internal/tsemit/templates/strict-json.ts.gotmpl @@ -0,0 +1,74 @@ +{{define "strict-json.ts"}} +type JSONSchema = { + ref?: string; + type?: string[]; + const?: unknown; + enum?: unknown[]; + additionalProperties?: boolean | JSONSchema; + properties?: Record; + required?: string[]; + items?: JSONSchema; + oneOf?: JSONSchema[]; + discriminator?: { propertyName: string; mapping: Record }; +}; + +const jsonSchemas: Record = {{.SchemasJSON}}; + +export function decodeJSON(value: unknown, schema: JSONSchema, path = '$'): unknown { + if (schema.ref !== undefined) { + const target = jsonSchemas[schema.ref]; + if (target === undefined) throw new Error(`unknown JSON schema ${schema.ref}`); + return decodeJSON(value, target, path); + } + if (schema.oneOf !== undefined) { + const discriminator = schema.discriminator; + if (discriminator !== undefined && Object.keys(discriminator.mapping).length > 0) { + if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${path}: expected object`); + const tag = (value as Record)[discriminator.propertyName]; + if (typeof tag !== 'string' || !Object.hasOwn(discriminator.mapping, tag)) throw new Error(`${path}: unknown discriminator ${String(tag)}`); + return decodeJSON(value, { ref: discriminator.mapping[tag] }, path); + } + let matches = 0; + for (const variant of schema.oneOf) { + try { decodeJSON(value, variant, path); matches++; } catch { /* try next variant */ } + } + if (matches !== 1) throw new Error(`${path}: expected exactly one JSON variant`); + return value; + } + if (schema.type !== undefined) { + const valid = schema.type.some(type => { + switch (type) { + case 'null': return value === null; + case 'array': return Array.isArray(value); + case 'object': return value !== null && typeof value === 'object' && !Array.isArray(value); + case 'integer': return typeof value === 'number' && Number.isInteger(value); + case 'number': return typeof value === 'number' && Number.isFinite(value); + default: return typeof value === type; + } + }); + if (!valid) throw new Error(`${path}: expected ${schema.type.join(' or ')}`); + } + if (Object.hasOwn(schema, 'const') && value !== schema.const) throw new Error(`${path}: invalid constant`); + if (schema.enum !== undefined && !schema.enum.includes(value)) throw new Error(`${path}: unknown enum value`); + if (value !== null && typeof value === 'object' && !Array.isArray(value)) { + const object = value as Record; + const properties = schema.properties ?? {}; + for (const key of schema.required ?? []) { + if (!Object.hasOwn(object, key)) throw new Error(`${path}.${key}: missing required field`); + } + for (const [key, item] of Object.entries(object)) { + if (Object.hasOwn(properties, key)) decodeJSON(item, properties[key], `${path}.${key}`); + else if (schema.additionalProperties === false) throw new Error(`${path}.${key}: unexpected JSON field`); + else if (typeof schema.additionalProperties === 'object') decodeJSON(item, schema.additionalProperties, `${path}.${key}`); + } + } + if (Array.isArray(value) && schema.items !== undefined) { + for (const [index, item] of value.entries()) decodeJSON(item, schema.items, `${path}[${index}]`); + } + return value; +} +{{range .Models}} +export function decode{{.Name}}(value: unknown): {{.Name}} { + return decodeJSON(value, { ref: '{{.Name}}' }) as {{.Name}}; +} +{{end}}{{end}} diff --git a/internal/tsemit/tsemit.go b/internal/tsemit/tsemit.go index adf1234..5e83c18 100644 --- a/internal/tsemit/tsemit.go +++ b/internal/tsemit/tsemit.go @@ -16,7 +16,9 @@ import ( // Options configures TypeScript client emission. type Options struct { - OutDir string + OutDir string + Strict bool + TypesOnly bool } //go:embed templates/*.gotmpl @@ -31,14 +33,23 @@ func Emit(doc *openapi.Document, opts Options) error { if err != nil { return err } - api, err := apiSource(doc) - if err != nil { - return err + if opts.Strict { + decoders, err := strictJSONSource(doc) + if err != nil { + return err + } + models += decoders } files := map[string]string{ - filepath.Join(opts.OutDir, "api.ts"): api, filepath.Join(opts.OutDir, "types.ts"): models, } + if !opts.TypesOnly { + api, err := apiSource(doc, opts.Strict) + if err != nil { + return err + } + files[filepath.Join(opts.OutDir, "api.ts")] = api + } for path, source := range files { if err := os.WriteFile(path, []byte(source), 0o644); err != nil { return fmt.Errorf("write %s: %w", path, err) @@ -113,13 +124,14 @@ func modelsTemplateData(doc *openapi.Document) modelsData { return data } -func apiSource(doc *openapi.Document) (string, error) { +func apiSource(doc *openapi.Document, strict bool) (string, error) { operations, err := clientgen.Analyze(doc) if err != nil { return "", fmt.Errorf("analyze client operations: %w", err) } data := apiData{ Imports: modelImports(doc, operations), + Strict: strict, } for _, analyzed := range operations { params := operationParams(analyzed) @@ -130,6 +142,17 @@ func apiSource(doc *openapi.Document) (string, error) { }) } operation := operationTemplateData(analyzed) + if strict { + for index, response := range analyzed.Responses { + if response.JSON() { + schema, err := jsonSchemaSource(response.Schema) + if err != nil { + return "", err + } + operation.Responses[index].Schema = schema + } + } + } if operation.HasSSE { data.HasSSE = true } @@ -142,6 +165,7 @@ func apiSource(doc *openapi.Document) (string, error) { } type apiData struct { + Strict bool Imports []string HasSSE bool HasMultipartBody bool @@ -263,6 +287,7 @@ type opParam struct { } type opResponse struct { + Schema string Status int Type string Body bool diff --git a/moon.yml b/moon.yml index 8c2a524..088ca1e 100644 --- a/moon.yml +++ b/moon.yml @@ -66,7 +66,7 @@ tasks: script: |- set -euo pipefail go run ./cmd/oasmith --openapi testdata/fixtures/public-client.yaml --mode client --lang rust --out testdata/rust-client/src/public - go run ./cmd/oasmith --openapi testdata/fixtures/rust-models.yaml --mode types --lang rust --out testdata/rust-client/src/models + go run ./cmd/oasmith --openapi testdata/fixtures/rust-models.yaml --mode types --lang rust --strict --out testdata/rust-client/src/models go run ./cmd/oasmith --openapi testdata/fixtures/rust-responses.yaml --mode client --lang rust --out testdata/rust-client/src/responses outputs: - testdata/rust-client/src/public/mod.rs diff --git a/oasmith_test.go b/oasmith_test.go index 06ddf15..ab0082d 100644 --- a/oasmith_test.go +++ b/oasmith_test.go @@ -1,17 +1,79 @@ package oasmith_test import ( + "context" "os" "os/exec" "path/filepath" "strings" "testing" + "time" + "github.com/responsibleapi/oasmith/internal/cli" "github.com/responsibleapi/oasmith/internal/goemit" "github.com/responsibleapi/oasmith/internal/openapi" "github.com/responsibleapi/oasmith/internal/tsemit" ) +func TestJSONDecodingPolicies(t *testing.T) { + t.Parallel() + for _, row := range []struct { + language, fixture, program string + command []string + }{ + {language: "go", fixture: "go-test.txt", program: "policy_test.go", command: []string{"go", "test", "-count=1", "./..."}}, + {language: "dart", fixture: "dart-check.dart", program: "check.dart", command: []string{"dart", "run", "check.dart"}}, + } { + t.Run(row.language, func(t *testing.T) { + t.Parallel() + ctx, cancel := context.WithTimeout(t.Context(), 9*time.Second) + defer cancel() + out := t.TempDir() + root, err := os.OpenRoot(out) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { + if err := root.Close(); err != nil { + t.Error(err) + } + }) + for _, policy := range []string{"api", "strict"} { + args := []string{"--openapi", "testdata/fixtures/json-policy.yaml", "--mode", "types", "--lang", row.language, "--out", filepath.Join(out, policy)} + if policy == "strict" { + args = append(args, "--strict") + } + if err := cli.Run(args); err != nil { + t.Fatalf("generate %s %s: %v", row.language, policy, err) + } + } + files := map[string]string{"cases.json": "testdata/fixtures/json-policy-cases.json", row.program: filepath.Join("testdata/json-policy", row.fixture)} + if err := root.WriteFile("go.mod", []byte("module policy\n\ngo 1.27.0\n"), 0o600); err != nil { + t.Fatal(err) + } + writeJSONPolicyFixtures(t, root, files) + command := exec.CommandContext(ctx, row.command[0], row.command[1:]...) + command.Dir = out + if output, err := command.CombinedOutput(); err != nil { + t.Fatalf("%s JSON policy contract: %v\n%s", row.language, err, output) + } + }) + } +} + +func writeJSONPolicyFixtures(t *testing.T, root *os.Root, files map[string]string) { + t.Helper() + for target, source := range files { + raw, err := os.ReadFile(source) + if err != nil { + t.Fatal(err) + } + if err := root.WriteFile(target, raw, 0o600); err != nil { + t.Fatal(err) + } + } +} + func TestGoldenFixtures(t *testing.T) { t.Parallel() diff --git a/testdata/fixtures/json-policy-cases.json b/testdata/fixtures/json-policy-cases.json new file mode 100644 index 0000000..c64c692 --- /dev/null +++ b/testdata/fixtures/json-policy-cases.json @@ -0,0 +1,7 @@ +[ + {"name":"known fields and open metadata","strict":true,"input":{"id":"podcast","source":{"url":"playlist"},"history":[{"url":"playlist"}],"connection":{"kind":"linked","source":{"url":"playlist"}},"metadata":{"new_field":{"nested":true}}}}, + {"name":"added root field","strict":false,"input":{"id":"podcast","apple_podcasts_url":"https://podcasts.apple.com/podcast/id123","source":{"url":"playlist"},"history":[],"connection":{"kind":"linked","source":{"url":"playlist"}},"metadata":{}}}, + {"name":"added nested field","strict":false,"input":{"id":"podcast","source":{"url":"playlist","new_field":true},"history":[],"connection":{"kind":"linked","source":{"url":"playlist"}},"metadata":{}}}, + {"name":"added array item field","strict":false,"input":{"id":"podcast","source":{"url":"playlist"},"history":[{"url":"playlist","new_field":null}],"connection":{"kind":"linked","source":{"url":"playlist"}},"metadata":{}}}, + {"name":"added tagged payload field","strict":false,"input":{"id":"podcast","source":{"url":"playlist"},"history":[],"connection":{"kind":"linked","source":{"url":"playlist"},"new_field":{"nested":[]}},"metadata":{}}} +] diff --git a/testdata/fixtures/json-policy.yaml b/testdata/fixtures/json-policy.yaml new file mode 100644 index 0000000..0a7da28 --- /dev/null +++ b/testdata/fixtures/json-policy.yaml @@ -0,0 +1,51 @@ +openapi: 3.2.0 +info: {title: JSON decoding policy, version: "1"} +paths: + /policy: + get: + operationId: getPolicy + responses: + "200": + description: Current configuration or an older client's HTTP payload + content: + application/json: + schema: + $ref: '#/components/schemas/Policy' +components: + schemas: + Policy: + type: object + additionalProperties: false + required: [id, source, connection, history, metadata] + properties: + id: {type: string} + source: + $ref: '#/components/schemas/Source' + history: + type: array + items: + $ref: '#/components/schemas/Source' + connection: + $ref: '#/components/schemas/Connection' + metadata: {type: object, additionalProperties: true} + Source: + type: object + additionalProperties: false + required: [url] + properties: + url: {type: string} + Connection: + oneOf: + - $ref: '#/components/schemas/Linked' + discriminator: + propertyName: kind + mapping: + linked: '#/components/schemas/Linked' + Linked: + type: object + additionalProperties: false + required: [kind, source] + properties: + kind: {type: string, const: linked} + source: + $ref: '#/components/schemas/Source' diff --git a/testdata/fixtures/rust-models.yaml b/testdata/fixtures/rust-models.yaml index b165348..9cc09aa 100644 --- a/testdata/fixtures/rust-models.yaml +++ b/testdata/fixtures/rust-models.yaml @@ -6,6 +6,7 @@ components: String: {type: string} Record: type: object + additionalProperties: false required: [type, nullable, self] properties: type: {type: string} diff --git a/testdata/fixtures/rust-responses.yaml b/testdata/fixtures/rust-responses.yaml index 8943c03..77e5cc8 100644 --- a/testdata/fixtures/rust-responses.yaml +++ b/testdata/fixtures/rust-responses.yaml @@ -3,6 +3,18 @@ info: title: Rust status response fixture version: "1" paths: + /catalog: + get: + operationId: listPodcasts + responses: + "200": + description: Podcasts known to an older client + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Podcast' /payload: get: operationId: getPayload @@ -26,3 +38,33 @@ paths: schema: type: string format: binary +components: + schemas: + Podcast: + type: object + additionalProperties: false + required: [id, title, youtube] + properties: + id: {type: string} + title: {type: string} + youtube: + $ref: '#/components/schemas/YouTube' + YouTube: + oneOf: + - $ref: '#/components/schemas/LinkedYouTube' + discriminator: + propertyName: status + mapping: + linked: '#/components/schemas/LinkedYouTube' + LinkedYouTube: + type: object + additionalProperties: false + required: [status, source] + properties: + status: {type: string, const: linked} + source: + type: object + additionalProperties: false + required: [url] + properties: + url: {type: string} diff --git a/testdata/json-policy/dart-check.dart b/testdata/json-policy/dart-check.dart new file mode 100644 index 0000000..3dadfc6 --- /dev/null +++ b/testdata/json-policy/dart-check.dart @@ -0,0 +1,25 @@ +import 'dart:convert'; +import 'dart:io'; +import 'api/models.dart' as api; +import 'strict/models.dart' as strict; + +void main() { + final cases = jsonDecode(File('cases.json').readAsStringSync()) as List; + for (final row in cases) { + final value = api.Policy.fromJson(row['input']); + if (value.id != 'podcast' || value.source.url != 'playlist') { + throw StateError('HTTP JSON lost known fields: ${row['name']}'); + } + var accepted = false; + try { + final config = strict.Policy.fromJson(row['input']); + if (config.id != 'podcast' || config.source.url != 'playlist') { + throw StateError('config lost known fields: ${row['name']}'); + } + accepted = true; + } on FormatException { /* Expected for extra fields in closed configs. */ } + if (accepted != row['strict']) { + throw StateError('strict decode: ${row['name']}; accepted=$accepted'); + } + } +} diff --git a/testdata/json-policy/go-test.txt b/testdata/json-policy/go-test.txt new file mode 100644 index 0000000..f882f1c --- /dev/null +++ b/testdata/json-policy/go-test.txt @@ -0,0 +1,30 @@ +package policy_test + +import ( + "encoding/json" + "os" + "testing" + + api "policy/api" + strict "policy/strict" +) + +func TestJSONPolicy(t *testing.T) { + t.Parallel() + raw, err := os.ReadFile("cases.json") + if err != nil { t.Fatal(err) } + var cases []struct { Name string; Input json.RawMessage; Strict bool } + if err := json.Unmarshal(raw, &cases); err != nil { t.Fatal(err) } + for _, row := range cases { + t.Run(row.Name, func(t *testing.T) { + t.Parallel() + var value api.Policy + if err := json.Unmarshal(row.Input, &value); err != nil { t.Fatalf("HTTP JSON: %v", err) } + if value.Id != "podcast" || value.Source.Url != "playlist" { t.Fatalf("HTTP JSON lost known fields: %+v", value) } + var config strict.Policy + err := json.Unmarshal(row.Input, &config) + if (err == nil) != row.Strict { t.Fatalf("strict decode: %v; want accepted=%v", err, row.Strict) } + if err == nil && (config.Id != "podcast" || config.Source.Url != "playlist") { t.Fatalf("config lost known fields: %+v", config) } + }) + } +} diff --git a/testdata/rust-client/src/lib.rs b/testdata/rust-client/src/lib.rs index 1b26773..2cc7d78 100644 --- a/testdata/rust-client/src/lib.rs +++ b/testdata/rust-client/src/lib.rs @@ -155,11 +155,53 @@ mod tests { assert!(value.nullable.is_none()); assert_eq!(value.self_value, "me"); assert!(value.optional.is_none()); + assert!(serde_json::from_value::(serde_json::json!({"type":"podcast", "nullable":null, "self":"me", "typo":true})).is_err()); let _: models::String = "string alias".into(); assert!(serde_json::from_value::(serde_json::json!({"status":"completed","thing":{"id":"a","name":"b"}})).is_ok()); assert!(serde_json::from_value::(serde_json::json!({"status":"unknown","message":"no"})).is_err()); } + #[tokio::test] + async fn older_clients_accept_additive_response_fields_but_reject_broken_payloads() { + use wiremock::{Mock, MockServer, ResponseTemplate, matchers::{method, path}}; + let work = async { + let server = MockServer::start().await; + let http = reqwest_middleware::ClientBuilder::new(reqwest::Client::builder().no_proxy().build().unwrap()).build(); + let api = responses::Client::new(http, server.uri(), None); + // The generated schema deliberately predates these response fields. + for body in [ + r#"[{"id":"podcast","title":"Podcast","apple_podcasts_url":"https://podcasts.apple.com/podcast/id123","youtube":{"status":"linked","source":{"url":"playlist"}}}]"#, + r#"[{"id":"podcast","title":"Podcast","youtube":{"status":"linked","last_checked_at":1700000000000,"source":{"url":"playlist"}}}]"#, + r#"[{"id":"podcast","title":"Podcast","youtube":{"status":"linked","source":{"url":"playlist","metadata":{"new_field":[1,null,true]}}}}]"#, + ] { + Mock::given(method("GET")).and(path("/catalog")) + .respond_with(ResponseTemplate::new(200).set_body_string(body)).expect(1).mount(&server).await; + let responses::ListPodcastsResponse::Status200(podcasts) = api.list_podcasts().await.unwrap() else { panic!("catalog did not load") }; + assert_eq!(podcasts.len(), 1); + assert_eq!(podcasts[0].id, "podcast"); + assert_eq!(podcasts[0].title, "Podcast"); + let responses::YouTube::Linked { source } = &podcasts[0].youtube; + assert_eq!(source.url, "playlist"); + server.verify().await; + server.reset().await; + } + for body in [ + r#"[{"title":"Podcast","youtube":{"status":"linked","source":{"url":"playlist"}}}]"#, + r#"[{"id":"podcast","title":42,"youtube":{"status":"linked","source":{"url":"playlist"}}}]"#, + r#"[{"id":"podcast","title":"Podcast","youtube":{"status":"unknown","source":{"url":"playlist"}}}]"#, + r#"[{"id":"podcast","title":"Podcast","youtube":{"status":"linked"}}]"#, + r#"[{"id":"podcast","title":"Podcast","youtube":{"status":"linked","source":{"url":false}}}]"#, + ] { + Mock::given(method("GET")).and(path("/catalog")) + .respond_with(ResponseTemplate::new(200).set_body_string(body)).expect(1).mount(&server).await; + assert!(matches!(api.list_podcasts().await, Err(responses::Error::Decode(_))), "accepted {body}"); + server.verify().await; + server.reset().await; + } + }; + tokio::time::timeout(std::time::Duration::from_secs(5), work).await.expect("response compatibility contract did not complete"); + } + #[tokio::test] async fn configured_client_propagates_the_context_active_at_send() { use opentelemetry::{global, Context};