Skip to content

fix: handle swagger:type array by falling through to underlying type resolution#11

Merged
fredbi merged 2 commits intogo-openapi:masterfrom
KT-Doan:fix/10-swagger-type-array
Apr 10, 2026
Merged

fix: handle swagger:type array by falling through to underlying type resolution#11
fredbi merged 2 commits intogo-openapi:masterfrom
KT-Doan:fix/10-swagger-type-array

Conversation

@KT-Doan
Copy link
Copy Markdown
Contributor

@KT-Doan KT-Doan commented Apr 9, 2026

Problem

When swagger:type is set to a value not handled by swaggerSchemaForType (e.g., array), the annotation is silently ignored in multiple code paths, producing incomplete or empty schemas.

This affects three named-type builder functions:

  • Type definitions (buildFromType): swaggerSchemaForType error was silently discarded with _ =, returning nil with no type info
  • Named slice fields (buildNamedSlice): no swagger:type check at all, always fell through to makeRef creating a $ref even when the type definition was suppressed
  • Named array fields (buildNamedArray): same as slices
  • Named struct fields (buildNamedStruct): swaggerSchemaForType error was silently discarded with _ =

Example

// swagger:type array
type StringSlice []string

// swagger:model myModel
type MyModel struct {
    Tags StringSlice `json:"tags"`
}

Before: Tags gets {"$ref": "#/definitions/StringSlice"} or an empty schema (description only, no type). The StringSlice definition is suppressed because swagger:type is present, so the $ref points to nothing.

After: Tags gets {"type": "array", "items": {"type": "string"}, "description": "..."} — correctly inlined with full type information and description preserved.

Fix

When swaggerSchemaForType returns an error for an unsupported type name:

  • buildFromType: fall through to s.buildFromType(underlying) to resolve the actual Go type
  • buildNamedSlice: skip makeRef, inline the slice by building from the element type
  • buildNamedArray: same approach as slices
  • buildNamedStruct: fall through to makeRef instead of returning an empty schema

This is backwards-compatible: supported type names (string, bool, int64, object, etc.) continue to work as before. Only previously-broken unsupported values now produce correct schemas.

Fixes #10

KT-Doan added a commit to ory-corp/go-swagger that referenced this pull request Apr 9, 2026
Add go.mod replace directive pointing go-openapi/codescan to
ory-corp/codescan which includes the fix for swagger:type array
producing incomplete schemas (missing items).

Upstream PR: go-openapi/codescan#11
Upstream issue: go-openapi/codescan#10

This replace should be removed once the upstream PR is merged
and a new go-swagger release includes it.

Signed-off-by: Kevin Doan <kevin.doan@ory.sh>
@KT-Doan KT-Doan force-pushed the fix/10-swagger-type-array branch from 1a7e648 to ec3df12 Compare April 9, 2026 07:00
KT-Doan added a commit to ory-corp/go-swagger that referenced this pull request Apr 9, 2026
Add go.mod replace directive pointing go-openapi/codescan to
ory-corp/codescan which includes the fix for swagger:type array
producing incomplete schemas (missing items).

Upstream PR: go-openapi/codescan#11
Upstream issue: go-openapi/codescan#10

This replace should be removed once the upstream PR is merged
and a new go-swagger release includes it.

Signed-off-by: Kevin Doan <kevin.doan@ory.sh>
Signed-off-by: KT-Doan <kevin.doan@ory.sh>
@KT-Doan KT-Doan force-pushed the fix/10-swagger-type-array branch from ec3df12 to 2e04a26 Compare April 9, 2026 08:26
KT-Doan added a commit to ory-corp/go-swagger that referenced this pull request Apr 9, 2026
Add go.mod replace directive pointing go-openapi/codescan to
ory-corp/codescan which includes the fix for swagger:type array
producing incomplete schemas (missing items).

Upstream PR: go-openapi/codescan#11
Upstream issue: go-openapi/codescan#10

This replace should be removed once the upstream PR is merged
and a new go-swagger release includes it.

Signed-off-by: Kevin Doan <kevin.doan@ory.sh>
Signed-off-by: KT-Doan <kevin.doan@ory.sh>
@KT-Doan KT-Doan force-pushed the fix/10-swagger-type-array branch from 2e04a26 to 57152d0 Compare April 9, 2026 10:05
KT-Doan added a commit to ory-corp/go-swagger that referenced this pull request Apr 9, 2026
Add go.mod replace directive pointing go-openapi/codescan to
ory-corp/codescan which includes the fix for swagger:type array
producing incomplete schemas (missing items).

Upstream PR: go-openapi/codescan#11
Upstream issue: go-openapi/codescan#10

This replace should be removed once the upstream PR is merged
and a new go-swagger release includes it.

Signed-off-by: Kevin Doan <kevin.doan@ory.sh>
Signed-off-by: KT-Doan <kevin.doan@ory.sh>
@codecov
Copy link
Copy Markdown

codecov bot commented Apr 10, 2026

Codecov Report

❌ Patch coverage is 26.66667% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.34%. Comparing base (7e52966) to head (6c1ce4b).
⚠️ Report is 5 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
schema.go 26.66% 8 Missing and 3 partials ⚠️

❌ Your patch status has failed because the patch coverage (26.66%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files
@@            Coverage Diff             @@
##           master      #11      +/-   ##
==========================================
- Coverage   72.43%   72.34%   -0.10%     
==========================================
  Files          14       14              
  Lines        3795     3804       +9     
==========================================
+ Hits         2749     2752       +3     
- Misses        734      738       +4     
- Partials      312      314       +2     

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

@KT-Doan
Copy link
Copy Markdown
Contributor Author

KT-Doan commented Apr 10, 2026

Codecov Report

❌ Patch coverage is 26.66667% with 11 lines in your changes missing coverage. Please review. ✅ Project coverage is 72.34%. Comparing base (7e52966) to head (57152d0). ⚠️ Report is 4 commits behind head on master. ✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
schema.go 26.66% 8 Missing and 3 partials ⚠️
❌ Your patch check has failed because the patch coverage (26.66%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #11      +/-   ##
==========================================
- Coverage   72.43%   72.34%   -0.10%     
==========================================
  Files          14       14              
  Lines        3795     3804       +9     
==========================================
+ Hits         2749     2752       +3     
- Misses        734      738       +4     
- Partials      312      314       +2     

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

Ah I didn't add tests for the other three fixes, let me do that now.

…resolution

When swagger:type is set to a value not handled by swaggerSchemaForType
(e.g., "array"), the function returns an error. Previously this error was
silently ignored and the function returned nil, losing all type info.

Now, when swaggerSchemaForType returns an error, the code falls through
to buildFromType with the underlying type, producing the correct schema.
For example, swagger:type array on type StringSlice []string now produces
{type: "array", items: {type: "string"}} with the field's description
preserved, instead of a $ref that drops the description.

* fixes go-openapi#10

Signed-off-by: Kevin Doan <kevin.doan@ory.sh>
Signed-off-by: KT-Doan <kevin.doan@ory.sh>
@KT-Doan KT-Doan force-pushed the fix/10-swagger-type-array branch from 57152d0 to 0e87d63 Compare April 10, 2026 06:22
@KT-Doan
Copy link
Copy Markdown
Contributor Author

KT-Doan commented Apr 10, 2026

@fredbi I added the remaining tests! please approve the workflow when you have the chance 🙇

@fredbi
Copy link
Copy Markdown
Member

fredbi commented Apr 10, 2026

Thanks. Really appreciate this fix.
The whole point of making this a separate lib was to allow for easier fixing like this one. Thanks for your contribution !

@fredbi fredbi merged commit 4be7125 into go-openapi:master Apr 10, 2026
20 of 21 checks passed
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.

swagger:type array produces incomplete schema (missing items)

2 participants