Skip to content

Commit 6ce3bd4

Browse files
fredbiclaude
andcommitted
fix(parsers): accept a one-character tag or operationId in a route
Both names had to be a letter followed by at least one more character, so a single-character tag or operationId did not match. OAS 2.0 puts no such floor on either — both are free-form strings, and a one-letter tag is ordinary. The annotation did not merely lose the short name, it disappeared whole. The tags group is optional, so `swagger:route GET /pets e listPets` did not fail at `e`: it fell back to matching with no tags, leaving the operationId pattern to swallow `e listPets`, whose alphabet has no space in it. The line then matched nothing at all — and a swagger:route that matches nothing is not a malformed route, it is not a route, so the path simply never appeared and nothing anywhere said why. Applies to swagger:operation identically; both share the two patterns. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 361e2f2 commit 6ce3bd4

5 files changed

Lines changed: 274 additions & 2 deletions

File tree

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
// Package route_name_shapes witnesses the name shapes a path annotation accepts,
5+
// and what happens to one it cannot parse.
6+
//
7+
// A tag and an operationId of a SINGLE character used to void the entire
8+
// annotation. The failure was not local to the short name: the tags group is
9+
// optional, so the parse fell back to matching with no tags at all, leaving the
10+
// operationId pattern to swallow `e listOne` — which its alphabet has no space
11+
// for. The line then matched nothing, and a swagger:route matching nothing is
12+
// not a malformed route, it is not a route, so no diagnostic was possible and
13+
// the path simply never appeared.
14+
package route_name_shapes
15+
16+
// HandlerShortTag has a one-character tag.
17+
//
18+
// swagger:route GET /short-tag e listOne
19+
//
20+
// Responses:
21+
//
22+
// 200: emptyResp
23+
func HandlerShortTag() {}
24+
25+
// HandlerShortID has a one-character operationId.
26+
//
27+
// swagger:route GET /short-id shapes l
28+
//
29+
// Responses:
30+
//
31+
// 200: emptyResp
32+
func HandlerShortID() {}
33+
34+
// HandlerShortBoth has both, which is where the fallback used to bite hardest.
35+
//
36+
// swagger:route GET /short-both e l
37+
//
38+
// Responses:
39+
//
40+
// 200: emptyResp
41+
func HandlerShortBoth() {}
42+
43+
// HandlerShortIDNoTags has a one-character operationId and no tags at all.
44+
//
45+
// swagger:route GET /short-id-no-tags q
46+
//
47+
// Responses:
48+
//
49+
// 200: emptyResp
50+
func HandlerShortIDNoTags() {}
51+
52+
// HandlerShortAmongTags carries a one-character tag beside a longer one.
53+
//
54+
// swagger:route GET /short-among a shapes listAmong
55+
//
56+
// Responses:
57+
//
58+
// 200: emptyResp
59+
func HandlerShortAmongTags() {}
60+
61+
// EmptyResp is the shared response body.
62+
//
63+
// swagger:response emptyResp
64+
type EmptyResp struct {
65+
// in: body
66+
Body string `json:"body"`
67+
}
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{
2+
"swagger": "2.0",
3+
"paths": {
4+
"/short-among": {
5+
"get": {
6+
"tags": [
7+
"a",
8+
"shapes"
9+
],
10+
"operationId": "listAmong",
11+
"responses": {
12+
"200": {
13+
"$ref": "#/responses/emptyResp"
14+
}
15+
}
16+
}
17+
},
18+
"/short-both": {
19+
"get": {
20+
"tags": [
21+
"e"
22+
],
23+
"operationId": "l",
24+
"responses": {
25+
"200": {
26+
"$ref": "#/responses/emptyResp"
27+
}
28+
}
29+
}
30+
},
31+
"/short-id": {
32+
"get": {
33+
"tags": [
34+
"shapes"
35+
],
36+
"operationId": "l",
37+
"responses": {
38+
"200": {
39+
"$ref": "#/responses/emptyResp"
40+
}
41+
}
42+
}
43+
},
44+
"/short-id-no-tags": {
45+
"get": {
46+
"operationId": "q",
47+
"responses": {
48+
"200": {
49+
"$ref": "#/responses/emptyResp"
50+
}
51+
}
52+
}
53+
},
54+
"/short-tag": {
55+
"get": {
56+
"tags": [
57+
"e"
58+
],
59+
"operationId": "listOne",
60+
"responses": {
61+
"200": {
62+
"$ref": "#/responses/emptyResp"
63+
}
64+
}
65+
}
66+
}
67+
},
68+
"responses": {
69+
"emptyResp": {
70+
"description": "EmptyResp is the shared response body.",
71+
"schema": {
72+
"type": "string"
73+
}
74+
}
75+
}
76+
}
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package integration_test
5+
6+
import (
7+
"testing"
8+
9+
"github.com/go-openapi/codescan"
10+
"github.com/go-openapi/codescan/internal/scantest"
11+
"github.com/go-openapi/testify/v2/assert"
12+
"github.com/go-openapi/testify/v2/require"
13+
)
14+
15+
// A tag or an operationId of a single character is ordinary in OAS 2.0 — both are free-form strings
16+
// — and used to void the whole `swagger:route` it appeared in.
17+
//
18+
// The failure was not local to the short name, which is why it was so quiet. The tags group is
19+
// optional, so the parse did not stop when `e` failed to match: it fell back to matching with NO
20+
// tags, leaving the operationId pattern to swallow `e listOne`, whose alphabet has no space in it.
21+
// The line then matched nothing at all — and a `swagger:route` that matches nothing is not a
22+
// malformed route, it is simply not a route. Nothing downstream could tell it apart from prose, so
23+
// there was nothing to report and the path just never appeared.
24+
func TestRouteNameShapes(t *testing.T) {
25+
doc, err := codescan.Run(&codescan.Options{
26+
Packages: []string{"./enhancements/route-name-shapes/..."},
27+
WorkDir: scantest.FixturesDir(),
28+
})
29+
require.NoError(t, err)
30+
require.NotNil(t, doc)
31+
require.NotNil(t, doc.Paths)
32+
33+
for _, tc := range []struct {
34+
path string
35+
wantID string
36+
wantTag []string
37+
}{
38+
{path: "/short-tag", wantID: "listOne", wantTag: []string{"e"}},
39+
{path: "/short-id", wantID: "l", wantTag: []string{"shapes"}},
40+
{path: "/short-both", wantID: "l", wantTag: []string{"e"}},
41+
{path: "/short-id-no-tags", wantID: "q"},
42+
{path: "/short-among", wantID: "listAmong", wantTag: []string{"a", "shapes"}},
43+
} {
44+
t.Run(tc.path, func(t *testing.T) {
45+
item, ok := doc.Paths.Paths[tc.path]
46+
require.True(t, ok, "no path %s: the annotation did not parse", tc.path)
47+
require.NotNil(t, item.Get)
48+
assert.Equal(t, tc.wantID, item.Get.ID)
49+
assert.Equal(t, tc.wantTag, item.Get.Tags)
50+
})
51+
}
52+
53+
// The per-path assertions above say the annotations parsed; the golden says what they produced.
54+
scantest.CompareOrDumpJSON(t, doc, "enhancements_route_name_shapes.json")
55+
}

‎internal/parsers/parsed_path_content_test.go‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,52 @@ func TestParseRoutePathAnnotation(t *testing.T) {
5353
wantID: "deletePet",
5454
wantTags: []string{"pets", "admin"},
5555
},
56+
57+
// One-character names. Both regexes used to require a letter followed by AT LEAST ONE more
58+
// character, and since the tags group is optional the parse did not fail there — it fell back to
59+
// matching with no tags, leaving the operationId pattern to swallow `e listPets`, which its
60+
// alphabet has no space for. The line then matched nothing at all, and a `swagger:route` that
61+
// matches nothing is not a malformed route but simply not a route: the whole annotation vanished
62+
// without a word. Neither restriction has any basis in OAS 2.0.
63+
{
64+
name: "single-character tag",
65+
line: "// swagger:route GET /pets e listPets",
66+
wantMethod: "GET",
67+
wantPath: "/pets",
68+
wantID: "listPets",
69+
wantTags: []string{"e"},
70+
},
71+
{
72+
name: "single-character operationId",
73+
line: "// swagger:route GET /pets pets l",
74+
wantMethod: "GET",
75+
wantPath: "/pets",
76+
wantID: "l",
77+
wantTags: []string{"pets"},
78+
},
79+
{
80+
name: "single-character operationId, no tags",
81+
line: "// swagger:route GET /pets l",
82+
wantMethod: "GET",
83+
wantPath: "/pets",
84+
wantID: "l",
85+
},
86+
{
87+
name: "single-character tag and operationId",
88+
line: "// swagger:route GET /pets e l",
89+
wantMethod: "GET",
90+
wantPath: "/pets",
91+
wantID: "l",
92+
wantTags: []string{"e"},
93+
},
94+
{
95+
name: "one-character tag among several",
96+
line: "// swagger:route DELETE /pets/{petId} a admin deletePet",
97+
wantMethod: "DELETE",
98+
wantPath: "/pets/{petId}",
99+
wantID: "deletePet",
100+
wantTags: []string{"a", "admin"},
101+
},
56102
}
57103

58104
for _, tc := range tests {
@@ -82,6 +128,22 @@ func TestParseOperationPathAnnotation(t *testing.T) {
82128
wantID string
83129
wantTags []string
84130
}{
131+
{
132+
name: "single-character tag",
133+
line: "// swagger:operation GET /v1/pets e listPets",
134+
wantMethod: "GET",
135+
wantPath: "/v1/pets",
136+
wantID: "listPets",
137+
wantTags: []string{"e"},
138+
},
139+
{
140+
name: "single-character operationId",
141+
line: "// swagger:operation GET /v1/pets pets l",
142+
wantMethod: "GET",
143+
wantPath: "/v1/pets",
144+
wantID: "l",
145+
wantTags: []string{"pets"},
146+
},
85147
{
86148
name: "basic operation",
87149
line: "// swagger:operation POST /v1/pets pets addPet",

‎internal/parsers/regexprs.go‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,20 @@ const (
3030

3131
rxMethod = "(\\p{L}+)"
3232
rxPath = "((?:/[\\p{L}\\p{N}\\p{Pd}\\p{Pc}{}\\-\\.\\?_~%!$&'()*+,;=:@/]*)+/?)"
33-
rxOpTags = "(\\p{L}[\\p{L}\\p{N}\\p{Pd}\\.\\p{Pc}\\p{Zs}]+)"
34-
rxOpID = "((?:\\p{L}[\\p{L}\\p{N}\\p{Pd}\\p{Pc}]+)+)"
33+
34+
// rxOpTags and rxOpID both accept a name of a SINGLE character: a letter, then zero or more
35+
// further characters.
36+
//
37+
// They required one further character until 2026-08-02, which silently voided the whole
38+
// annotation. The failure is not local to the offending name, because the tags group is optional:
39+
// on `swagger:route GET /pets e listPets` the parse does not stop at `e`, it falls back to matching
40+
// with NO tags, which leaves rxOpID to swallow `e listPets` — and its alphabet has no space. The
41+
// line then matches nothing, and a `swagger:route` matching nothing is not a malformed route, it is
42+
// not a route at all, so there was nothing left to raise a diagnostic about.
43+
//
44+
// OAS 2.0 puts no such floor on either: a tag and an operationId are free-form strings.
45+
rxOpTags = "(\\p{L}[\\p{L}\\p{N}\\p{Pd}\\.\\p{Pc}\\p{Zs}]*)"
46+
rxOpID = "(\\p{L}[\\p{L}\\p{N}\\p{Pd}\\p{Pc}]*)"
3547
)
3648

3749
// compile-once regexes; read-only.

0 commit comments

Comments
 (0)
⌂ 换网址