René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Types from an import-mapped document are qualified as a whole, producing `externalRef0.any`, `externalRef0.*string`, `externalRef0.[]Thing`","articleBody":"Found while reviewing #2514; pre-existing on `main` and independent of that PR.\n\n## Problem\n\nWhen generated code refers to a type that belongs to an import-mapped document, the generator qualifies it by putting the package name in front of the *whole* Go type (`ensureExternalRefsInSchema` in `pkg/codegen/externalref.go`). That is only right when the type is a single model name (`Thing` → `externalRef0.Thing`). Every other spelling breaks:\n\n```go\nBody       externalRef0.any                          // undefined\nLimit      *externalRef0.int                         // undefined\nBody       externalRef0.*string                      // gofmt: expected 'IDENT', found '*'\ntype OpJSONRequestBody = externalRef0.[]Thing        // gofmt: expected 'IDENT', found '['\nBody       externalRef0.time.Time                    // gofmt: expected ';', found '.'\n```\n\nStruct literals are skipped instead of qualified, so a model named inside one stays a bare local name: `undefined: Thing`, or worse, if the importing package declares its own `Thing`, it silently refers to that type and decodes into the wrong shape. Response headers of a reused path item have the same problem.\n\nTwo positions are affected:\n\n- **A reusable response reached from a non-fixed status code** (`default`, `2XX`), or reused by a second status code, when it comes from another document. The operation declares its own `Body \u003ctype>` field, and that type is mis-qualified.\n- **Every inline schema of an operation in a path item reused by `$ref`** (`/things: $ref: ./common.yaml#/paths/~1things`): its parameters, its request body, and its responses. In the same position, response headers aren't qualified at all, and neither are the client's typed responses (`JSON200 *Thing` → `undefined: Thing`).\n\nIn practice, any primitive, array, map, pointer, `format: date-time`/`uuid` or `x-go-type` schema in those positions fails. Only a `$ref` to a model, or a plain inline object without model fields, works today.\n\n## Reproduction\n\n`common.yaml`:\n\n```yaml\nopenapi: \"3.0.3\"\ninfo: {title: common, version: \"1\"}\npaths:\n  /things:\n    get:\n      operationId: listThings\n      parameters:\n        - {name: limit, in: query, schema: {type: integer}}\n      responses:\n        default:\n          description: error\n          content:\n            application/json:\n              schema: {}\ncomponents:\n  responses:\n    Untyped:\n      description: untyped\n      content:\n        application/json:\n          schema: {}\n```\n\n`api.yaml`:\n\n```yaml\nopenapi: \"3.0.3\"\ninfo: {title: api, version: \"1\"}\npaths:\n  /things:\n    $ref: \"./common.yaml#/paths/~1things\"\n  /other:\n    get:\n      operationId: getOther\n      responses:\n        default:\n          $ref: \"./common.yaml#/components/responses/Untyped\"\n```\n\nConfigs: `common.yaml` with `generate: {models: true, std-http-server: true, strict-server: true}`; `api.yaml` with the same plus `import-mapping: {./common.yaml: \u003ccommon package>}`. The `api` package does not compile:\n\n```\napi.gen.go:21:9: undefined: externalRef0     // Limit *externalRef0.int\napi.gen.go:224:13: undefined: externalRef0   // Body externalRef0.any (getOther)\napi.gen.go:249:13: undefined: externalRef0   // Body externalRef0.any (listThings default)\n```\n\n(The import is missing because nothing else refers to the package.) Adding a reusable response whose schema is `x-go-type: \"*string\"`, or an array such as `type: array, items: {$ref: '#/components/schemas/Thing'}`, referenced from a `default` status, makes generation itself fail:\n\n```\nerror generating code: error formatting Go code at line 360: api.go:360:39: expected 'IDENT', found '*' (and 2 more errors)\n```\n\n## Notes\n\n- Since none of this output compiles, the fix is free to choose the right shape: qualify only the model names inside the type (`[]externalRef0.Thing`), and leave builtins (`any`, `*string`) and already-qualified names (`time.Time`, `openapi_types.UUID`) alone.\n- A single model name, and a struct literal that the schema declares as a named type, already work and must keep their current spelling. For example, under `old-aliasing` the imported package declares a request-body type as a defined type rather than an alias, so switching which name is referenced would change type identity.\n- #2514 fixes a separate problem that also shows up here: under strict-server, an inline `schema: {}` response with a fixed status code doesn't compile in either package. With both fixes, reused path items with untyped responses compile.\n","author":{"url":"https://github.com/mromaszewicz","@type":"Person","name":"mromaszewicz"},"datePublished":"2026-09-27T22:55:31Z","url":"https://github.com/oapi-codegen/oapi-codegen/issues/2588"}