Backwards compatibility flag for alias handling

[cce]

Summary

Adds a new --transparent-aliases flag to swagger generate spec that makes type aliases completely transparent during spec generation. When enabled, aliases never create their own definitions in the swagger spec - references point directly to the underlying type instead.

This provides a backwards compatibility option for projects that depend on stable swagger specs and were affected by the alias handling changes in #3227.

Motivation

PR #3227 improved Go 1.24 compatibility and added proper support for type aliases by creating swagger definitions for them. While this is the correct default behavior (aliases are distinct types in the API surface), it changed the generated swagger specs for existing codebases, which be disruptive.

Solution

The --transparent-aliases flag restores the pre-#3227 behavior where type aliases are treated as completely transparent to the spec generation process:

type Identifier string
type UserID = Identifier  // alias

type User struct {
    ID UserID `json:"id"`
}

Without flag (default):
Generates swagger with three definitions:

"definitions": {
  "Identifier": {"type": "string"},
  "UserID": {"$ref": "#/definitions/Identifier"},
  "User": {
    "properties": {
      "id": {"$ref": "#/definitions/UserID"}
    }
  }
}

With --transparent-aliases:
Generates swagger with two definitions (UserID omitted):

"definitions": {
  "Identifier": {"type": "string"},
  "User": {
    "properties": {
      "id": {"$ref": "#/definitions/Identifier"}
    }
  }
}

Example

See examples/alias-compatibility/ for a minimal working example demonstrating the difference.

Testing

• Added unit tests comparing output with and without the flag
• Verified existing tests continue to pass
• Tested with go-algorand's real-world API definitions

Related

• Complements the existing --with-expand flag (which expands all $ref entries)
• Works alongside --flatten options
• Does not affect the RefAliases scanner option (which controls whether aliases are expanded or define their own model and are referred to by $ref).

[fredbi]

OK I understand the requirement. This is a good thing.
Could you please update the CLI doc which is published: docs/generate-spec/_index.md ?

[codecov]

Codecov Report

❌ Patch coverage is 80.43478% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.95%. Comparing base (e69250a) to head (01d6c41).
⚠️ Report is 2 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
codescan/parameters.go	82.35%	2 Missing and 1 partial ⚠️
codescan/responses.go	80.00%	2 Missing and 1 partial ⚠️
codescan/schema.go	62.50%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3239      +/-   ##
==========================================
+ Coverage   80.73%   80.95%   +0.22%     
==========================================
  Files          64       64              
  Lines       13823    13869      +46     
==========================================
+ Hits        11160    11228      +68     
+ Misses       2075     2049      -26     
- Partials      588      592       +4     

Flag	Coverage Δ
-	80.95% <80.43%> (?)
codegen-oldstable-canary-fixtures	?
codegen-stable-canary-fixtures	?
unit-oldstable	?
unit-stable	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[fredbi]

NOTE: RefAliases does not control whether aliases a recognized at all, but whether aliases are expanded or define their own model and referred to by $ref.

[fredbi]

Another point: since you've changed the behavior for parameters and responses too, could you please add a test case that reasonably covers that part of the patch?

[cce]

Thanks, I think I've addressed your feedback with some more test fixtures and updated the docs. Also, thanks for developing and maintaining this tool!

[fredbi]

Looks great. Thank you for this contribution.