Skip to content

feat: add support for using package name for external ref imports#2193

Closed
InventivetalentDev wants to merge 6 commits intooapi-codegen:mainfrom
InventivetalentDev:feat/external-ref
Closed

feat: add support for using package name for external ref imports#2193
InventivetalentDev wants to merge 6 commits intooapi-codegen:mainfrom
InventivetalentDev:feat/external-ref

Conversation

@InventivetalentDev
Copy link

@InventivetalentDev InventivetalentDev commented Feb 2, 2026

Adds a new external-ref-named-imports option which changes aliases for external imports from externalRef0, externalRef1, ... to external_ref_<package_name> (e.g. external_ref_packageA, external_ref_packageB).
This allows for more consistent import names when dealing with large projects and multiple linked specs, where the same externalRef0 import can end up referencing different source packages.

Motivation

I'm using oapi-codegen in a complex project in combination with tygo to generate TS types for my frontend code. tygo also supports external imports, but they need to be explicitly mapped from the Go package to the TS file, so my config for that currently looks something like this:

type_mappings:
  time.Time: "string /* RFC3339 */"
  null.String: "null | string"
  null.Bool: "null | boolean"
  uuid.UUID: "string /* uuid */"

  externalRef0.User: User
  externalRef1.Project: Project
  externalRef1.Repo: Repo
  externalRef2.Identity: Identity
  // same source package but different ref index for a spec that doesn't import User or Project, leading to duplicate type mapping
  externalRef0.Identity: Identity 

needing to map the same package/type multiple times since different files have varying starting indexes for externalRef imports.
Using named-imports allows me to simply do this instead:

  external_ref_users.User: User
  external_ref_projects.Project: Project
  external_ref_projects.Repo: Repo
  external_ref_identities.Identity: Identity

@InventivetalentDev InventivetalentDev marked this pull request as ready for review February 2, 2026 10:26
@InventivetalentDev InventivetalentDev requested a review from a team as a code owner February 2, 2026 10:26
@mromaszewicz
Copy link
Member

How would you feel about doing this differently?

I think this approach is more complex than it needs to be, and we can get this in by allowing the specification of an import name in the import mapping.

Right now, you have something like:

import-mapping:
  ../common/api.yaml: github.com/oapi-codegen/oapi-codegen/v2/examples/import-mapping/common

We could accept spaces in there:

import-mapping:
  ../common/api.yaml: common github.com/oapi-codegen/oapi-codegen/v2/examples/import-mapping/common

I think it would be simpler to use. Basically, the entire line would be passed to import verbatim, as is, and you can put in user names, whatever. It's up to you. All we need to do is strings.Split(...), and if it's got 2 pieces, the first piece is the alias. If it's only got one piece, we use the externalRefX alias.

@InventivetalentDev
Copy link
Author

@mromaszewicz oh I like it, I'll look into that!

@InventivetalentDev
Copy link
Author

Continued in #2211 with a nicer implementation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants