Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 76701b8

Browse files
mtojekmtojek
committed
Assert: consistent ID and summary
1 parent 33d93d6 commit 76701b8

14 files changed

+80
-55
lines changed

‎coderd/apidoc/docs.go

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ const docTemplate = `{
145145
"Applications"
146146
],
147147
"summary": "Get applications host",
148-
"operationId": "get-app-host",
148+
"operationId": "get-applications-host",
149149
"responses": {
150150
"200": {
151151
"description": "OK",
@@ -223,7 +223,7 @@ const docTemplate = `{
223223
"Audit"
224224
],
225225
"summary": "Generate fake audit log",
226-
"operationId": "generate-fake-audit-logs",
226+
"operationId": "generate-fake-audit-log",
227227
"parameters": [
228228
{
229229
"description": "Audit log request",
@@ -405,7 +405,7 @@ const docTemplate = `{
405405
"Files"
406406
],
407407
"summary": "Upload file",
408-
"operationId": "update-file",
408+
"operationId": "upload-file",
409409
"parameters": [
410410
{
411411
"type": "string",
@@ -1656,7 +1656,7 @@ const docTemplate = `{
16561656
"Templates"
16571657
],
16581658
"summary": "Update template metadata by ID",
1659-
"operationId": "update-template-metadata",
1659+
"operationId": "update-template-metadata-by-id",
16601660
"parameters": [
16611661
{
16621662
"type": "string",
@@ -1806,7 +1806,7 @@ const docTemplate = `{
18061806
"Templates"
18071807
],
18081808
"summary": "List template versions by template ID",
1809-
"operationId": "list-template-versions-by-template-ID",
1809+
"operationId": "list-template-versions-by-template-id",
18101810
"parameters": [
18111811
{
18121812
"type": "string",
@@ -1864,7 +1864,7 @@ const docTemplate = `{
18641864
"Templates"
18651865
],
18661866
"summary": "Update active template version by template ID",
1867-
"operationId": "update-active-template-version-by-template-ID",
1867+
"operationId": "update-active-template-version-by-template-id",
18681868
"parameters": [
18691869
{
18701870
"description": "Modified template version",
@@ -2688,7 +2688,7 @@ const docTemplate = `{
26882688
"Users"
26892689
],
26902690
"summary": "OAuth 2.0 GitHub Callback",
2691-
"operationId": "oauth2-github-callback",
2691+
"operationId": "oauth-20-github-callback",
26922692
"responses": {
26932693
"307": {
26942694
"description": "Temporary Redirect"
@@ -2710,7 +2710,7 @@ const docTemplate = `{
27102710
"Users"
27112711
],
27122712
"summary": "OpenID Connect Callback",
2713-
"operationId": "oidc-callback",
2713+
"operationId": "openid-connect-callback",
27142714
"responses": {
27152715
"307": {
27162716
"description": "Temporary Redirect"
@@ -3044,7 +3044,7 @@ const docTemplate = `{
30443044
"Users"
30453045
],
30463046
"summary": "Delete API key",
3047-
"operationId": "delete-user-tokens",
3047+
"operationId": "delete-api-key",
30483048
"parameters": [
30493049
{
30503050
"type": "string",
@@ -3083,7 +3083,7 @@ const docTemplate = `{
30833083
"Users"
30843084
],
30853085
"summary": "Get organizations by user",
3086-
"operationId": "get-organizations-by-users",
3086+
"operationId": "get-organizations-by-user",
30873087
"parameters": [
30883088
{
30893089
"type": "string",
@@ -3627,8 +3627,8 @@ const docTemplate = `{
36273627
"tags": [
36283628
"Agents"
36293629
],
3630-
"summary": "Submit workspace application health",
3631-
"operationId": "submit-workspace-workspace-agent-health",
3630+
"summary": "Submit workspace agent application health",
3631+
"operationId": "submit-workspace-agent-application-health",
36323632
"parameters": [
36333633
{
36343634
"description": "Application health request",
@@ -3662,7 +3662,7 @@ const docTemplate = `{
36623662
"Agents"
36633663
],
36643664
"summary": "Coordinate workspace agent via Tailnet",
3665-
"operationId": "get-workspace-agent-git-ssh-key-via-tailnet",
3665+
"operationId": "coordinate-workspace-agent-via-tailnet",
36663666
"responses": {
36673667
"101": {
36683668
"description": "Switching Protocols"
@@ -3784,7 +3784,7 @@ const docTemplate = `{
37843784
"Agents"
37853785
],
37863786
"summary": "Submit workspace agent stats",
3787-
"operationId": "submit-workspace-workspace-agent-stats",
3787+
"operationId": "submit-workspace-agent-stats",
37883788
"parameters": [
37893789
{
37903790
"description": "Stats request",
@@ -3820,7 +3820,7 @@ const docTemplate = `{
38203820
"Agents"
38213821
],
38223822
"summary": "Submit workspace agent version",
3823-
"operationId": "submit-workspace-workspace-agent-version",
3823+
"operationId": "submit-workspace-agent-version",
38243824
"parameters": [
38253825
{
38263826
"description": "Version request",
@@ -3987,7 +3987,7 @@ const docTemplate = `{
39873987
"Agents"
39883988
],
39893989
"summary": "Open PTY to workspace agent",
3990-
"operationId": "open-pty-to-workspace agent",
3990+
"operationId": "open-pty-to-workspace-agent",
39913991
"parameters": [
39923992
{
39933993
"type": "string",
@@ -4213,7 +4213,7 @@ const docTemplate = `{
42134213
"Workspaces"
42144214
],
42154215
"summary": "List workspaces",
4216-
"operationId": "get-workspaces",
4216+
"operationId": "list-workspaces",
42174217
"parameters": [
42184218
{
42194219
"type": "string",
@@ -4611,7 +4611,7 @@ const docTemplate = `{
46114611
"Workspaces"
46124612
],
46134613
"summary": "Watch workspace by ID",
4614-
"operationId": "watch-workspace-id",
4614+
"operationId": "watch-workspace-by-id",
46154615
"parameters": [
46164616
{
46174617
"type": "string",

‎coderd/apidoc/swagger.json

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@
119119
"produces": ["application/json"],
120120
"tags": ["Applications"],
121121
"summary": "Get applications host",
122-
"operationId": "get-app-host",
122+
"operationId": "get-applications-host",
123123
"responses": {
124124
"200": {
125125
"description": "OK",
@@ -189,7 +189,7 @@
189189
"consumes": ["application/json"],
190190
"tags": ["Audit"],
191191
"summary": "Generate fake audit log",
192-
"operationId": "generate-fake-audit-logs",
192+
"operationId": "generate-fake-audit-log",
193193
"parameters": [
194194
{
195195
"description": "Audit log request",
@@ -341,7 +341,7 @@
341341
"produces": ["application/json"],
342342
"tags": ["Files"],
343343
"summary": "Upload file",
344-
"operationId": "update-file",
344+
"operationId": "upload-file",
345345
"parameters": [
346346
{
347347
"type": "string",
@@ -1444,7 +1444,7 @@
14441444
"produces": ["application/json"],
14451445
"tags": ["Templates"],
14461446
"summary": "Update template metadata by ID",
1447-
"operationId": "update-template-metadata",
1447+
"operationId": "update-template-metadata-by-id",
14481448
"parameters": [
14491449
{
14501450
"type": "string",
@@ -1578,7 +1578,7 @@
15781578
"produces": ["application/json"],
15791579
"tags": ["Templates"],
15801580
"summary": "List template versions by template ID",
1581-
"operationId": "list-template-versions-by-template-ID",
1581+
"operationId": "list-template-versions-by-template-id",
15821582
"parameters": [
15831583
{
15841584
"type": "string",
@@ -1630,7 +1630,7 @@
16301630
"produces": ["application/json"],
16311631
"tags": ["Templates"],
16321632
"summary": "Update active template version by template ID",
1633-
"operationId": "update-active-template-version-by-template-ID",
1633+
"operationId": "update-active-template-version-by-template-id",
16341634
"parameters": [
16351635
{
16361636
"description": "Modified template version",
@@ -2362,7 +2362,7 @@
23622362
"produces": ["application/json"],
23632363
"tags": ["Users"],
23642364
"summary": "OAuth 2.0 GitHub Callback",
2365-
"operationId": "oauth2-github-callback",
2365+
"operationId": "oauth-20-github-callback",
23662366
"responses": {
23672367
"307": {
23682368
"description": "Temporary Redirect"
@@ -2380,7 +2380,7 @@
23802380
"produces": ["application/json"],
23812381
"tags": ["Users"],
23822382
"summary": "OpenID Connect Callback",
2383-
"operationId": "oidc-callback",
2383+
"operationId": "openid-connect-callback",
23842384
"responses": {
23852385
"307": {
23862386
"description": "Temporary Redirect"
@@ -2674,7 +2674,7 @@
26742674
"produces": ["application/json"],
26752675
"tags": ["Users"],
26762676
"summary": "Delete API key",
2677-
"operationId": "delete-user-tokens",
2677+
"operationId": "delete-api-key",
26782678
"parameters": [
26792679
{
26802680
"type": "string",
@@ -2709,7 +2709,7 @@
27092709
"produces": ["application/json"],
27102710
"tags": ["Users"],
27112711
"summary": "Get organizations by user",
2712-
"operationId": "get-organizations-by-users",
2712+
"operationId": "get-organizations-by-user",
27132713
"parameters": [
27142714
{
27152715
"type": "string",
@@ -3195,8 +3195,8 @@
31953195
],
31963196
"produces": ["application/json"],
31973197
"tags": ["Agents"],
3198-
"summary": "Submit workspace application health",
3199-
"operationId": "submit-workspace-workspace-agent-health",
3198+
"summary": "Submit workspace agent application health",
3199+
"operationId": "submit-workspace-agent-application-health",
32003200
"parameters": [
32013201
{
32023202
"description": "Application health request",
@@ -3226,7 +3226,7 @@
32263226
"produces": ["application/json"],
32273227
"tags": ["Agents"],
32283228
"summary": "Coordinate workspace agent via Tailnet",
3229-
"operationId": "get-workspace-agent-git-ssh-key-via-tailnet",
3229+
"operationId": "coordinate-workspace-agent-via-tailnet",
32303230
"responses": {
32313231
"101": {
32323232
"description": "Switching Protocols"
@@ -3326,7 +3326,7 @@
33263326
"produces": ["application/json"],
33273327
"tags": ["Agents"],
33283328
"summary": "Submit workspace agent stats",
3329-
"operationId": "submit-workspace-workspace-agent-stats",
3329+
"operationId": "submit-workspace-agent-stats",
33303330
"parameters": [
33313331
{
33323332
"description": "Stats request",
@@ -3358,7 +3358,7 @@
33583358
"produces": ["application/json"],
33593359
"tags": ["Agents"],
33603360
"summary": "Submit workspace agent version",
3361-
"operationId": "submit-workspace-workspace-agent-version",
3361+
"operationId": "submit-workspace-agent-version",
33623362
"parameters": [
33633363
{
33643364
"description": "Version request",
@@ -3509,7 +3509,7 @@
35093509
],
35103510
"tags": ["Agents"],
35113511
"summary": "Open PTY to workspace agent",
3512-
"operationId": "open-pty-to-workspace agent",
3512+
"operationId": "open-pty-to-workspace-agent",
35133513
"parameters": [
35143514
{
35153515
"type": "string",
@@ -3711,7 +3711,7 @@
37113711
"produces": ["application/json"],
37123712
"tags": ["Workspaces"],
37133713
"summary": "List workspaces",
3714-
"operationId": "get-workspaces",
3714+
"operationId": "list-workspaces",
37153715
"parameters": [
37163716
{
37173717
"type": "string",
@@ -4064,7 +4064,7 @@
40644064
"produces": ["text/event-stream"],
40654065
"tags": ["Workspaces"],
40664066
"summary": "Watch workspace by ID",
4067-
"operationId": "watch-workspace-id",
4067+
"operationId": "watch-workspace-by-id",
40684068
"parameters": [
40694069
{
40704070
"type": "string",

‎coderd/apikey.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ func (api *API) tokens(rw http.ResponseWriter, r *http.Request) {
209209
}
210210

211211
// @Summary Delete API key
212-
// @ID delete-user-tokens
212+
// @ID delete-api-key
213213
// @Security CoderSessionToken
214214
// @Produce json
215215
// @Tags Users

‎coderd/audit.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
8989
}
9090

9191
// @Summary Generate fake audit log
92-
// @ID generate-fake-audit-logs
92+
// @ID generate-fake-audit-log
9393
// @Security CoderSessionToken
9494
// @Accept json
9595
// @Tags Audit

‎coderd/coderdtest/swagger_test.go

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import (
55
"go/parser"
66
"go/token"
77
"net/http"
8+
"regexp"
89
"strings"
910
"testing"
1011

@@ -15,6 +16,9 @@ import (
1516
)
1617

1718
type swaggerComment struct {
19+
summary string
20+
id string
21+
1822
method string
1923
router string
2024
}
@@ -35,6 +39,11 @@ func TestAllEndpointsDocumented(t *testing.T) {
3539

3640
c := findSwaggerCommentByMethodAndRoute(swaggerComments, method, route)
3741
assert.NotNil(t, c, "Missing @Router annotation for: [%s] %s", method, route)
42+
if c == nil {
43+
return nil // do not fail next assertion for this route
44+
}
45+
46+
assertConsistencyBetweenRouteIDAndSummary(t, *c)
3847
return nil
3948
})
4049
}
@@ -80,6 +89,12 @@ func parseSwaggerComment(commentGroup *ast.CommentGroup) swaggerComment {
8089
args := strings.SplitN(text, " ", 4)
8190
c.router = args[2]
8291
c.method = args[3][1 : len(args[3])-1]
92+
} else if strings.Contains(text, "@Summary ") {
93+
args := strings.SplitN(text, " ", 3)
94+
c.summary = args[2]
95+
} else if strings.Contains(text, "@ID ") {
96+
args := strings.SplitN(text, " ", 3)
97+
c.id = args[2]
8398
}
8499
}
85100
return c
@@ -93,3 +108,13 @@ func findSwaggerCommentByMethodAndRoute(comments []swaggerComment, method, route
93108
}
94109
return nil
95110
}
111+
112+
var nonAlphanumericRegex = regexp.MustCompile(`[^a-zA-Z0-9-]+`)
113+
114+
func assertConsistencyBetweenRouteIDAndSummary(t *testing.T, comment swaggerComment) {
115+
exp := strings.ToLower(comment.summary)
116+
exp = strings.ReplaceAll(exp, " ", "-")
117+
exp = nonAlphanumericRegex.ReplaceAllString(exp, "")
118+
119+
assert.Equal(t, exp, comment.id, "Router ID must match summary")
120+
}

‎coderd/files.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ const (
2525

2626
// @Summary Upload file
2727
// @Description Swagger notice: Swagger 2.0 doesn't support file upload with a `content-type` different than `application/x-www-form-urlencoded`.
28-
// @ID update-file
28+
// @ID upload-file
2929
// @Security CoderSessionToken
3030
// @Produce json
3131
// @Accept application/x-tar

0 commit comments

Comments
 (0)