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

Skip to content

Commit 9272c01

Browse files
mtojekmtojek
committed
Go comment goes to top
1 parent 1d30352 commit 9272c01

File tree

6 files changed

+62
-37
lines changed

6 files changed

+62
-37
lines changed

‎coderd/coderdtest/swaggertest.go renamed to ‎coderd/coderdtest/swaggerparser.go

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ type SwaggerComment struct {
2525

2626
hasSuccess bool
2727
hasFailure bool
28+
29+
raw []*ast.Comment
2830
}
2931

3032
func ParseSwaggerComments(dirs ...string) ([]SwaggerComment, error) {
@@ -64,7 +66,9 @@ func ParseSwaggerComments(dirs ...string) ([]SwaggerComment, error) {
6466
}
6567

6668
func parseSwaggerComment(commentGroup *ast.CommentGroup) SwaggerComment {
67-
var c SwaggerComment
69+
c := SwaggerComment{
70+
raw: commentGroup.List,
71+
}
6872
for _, line := range commentGroup.List {
6973
splitN := strings.SplitN(strings.TrimSpace(line.Text), " ", 2)
7074
if len(splitN) < 2 {
@@ -113,6 +117,7 @@ func VerifySwaggerDefinitions(t *testing.T, router chi.Router, swaggerComments [
113117
assertConsistencyBetweenRouteIDAndSummary(t, *c)
114118
assertSuccessOrFailureDefined(t, *c)
115119
assertRequiredAnnotations(t, *c)
120+
assertGoCommentFirst(t, *c)
116121
})
117122
return nil
118123
})
@@ -147,3 +152,21 @@ func assertRequiredAnnotations(t *testing.T, comment SwaggerComment) {
147152
assert.NotEmpty(t, comment.summary, "@Summary must be defined")
148153
assert.NotEmpty(t, comment.tags, "@Tags must be defined")
149154
}
155+
156+
func assertGoCommentFirst(t *testing.T, comment SwaggerComment) {
157+
var inSwaggerBlock bool
158+
159+
for _, line := range comment.raw {
160+
text := strings.TrimSpace(line.Text)
161+
162+
if inSwaggerBlock {
163+
if !strings.HasPrefix(text, "// @") {
164+
assert.Fail(t, "Go function comment must be placed before swagger comments")
165+
return
166+
}
167+
}
168+
if strings.HasPrefix(text, "// @Summary") {
169+
inSwaggerBlock = true
170+
}
171+
}
172+
}

‎coderd/templates.go

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ import (
2323
"github.com/coder/coder/examples"
2424
)
2525

26+
// Returns a single template.
27+
//
2628
// @Summary Get template metadata by ID
2729
// @ID get-template-metadata-by-id
2830
// @Security CoderSessionToken
@@ -31,7 +33,6 @@ import (
3133
// @Param template path string true "Template ID" format(uuid)
3234
// @Success 200 {object} codersdk.Template
3335
// @Router /templates/{template} [get]
34-
// Returns a single template.
3536
func (api *API) template(rw http.ResponseWriter, r *http.Request) {
3637
ctx := r.Context()
3738
template := httpmw.TemplateParam(r)
@@ -131,6 +132,9 @@ func (api *API) deleteTemplate(rw http.ResponseWriter, r *http.Request) {
131132
})
132133
}
133134

135+
// Create a new template in an organization.
136+
// Returns a single template.
137+
//
134138
// @Summary Create template by organization
135139
// @ID create-template-by-organization
136140
// @Security CoderSessionToken
@@ -141,8 +145,6 @@ func (api *API) deleteTemplate(rw http.ResponseWriter, r *http.Request) {
141145
// @Param organization path string true "Organization ID"
142146
// @Success 200 {object} codersdk.Template
143147
// @Router /organizations/{organization}/templates [post]
144-
// Returns a single template.
145-
// Create a new template in an organization.
146148
func (api *API) postTemplateByOrganization(rw http.ResponseWriter, r *http.Request) {
147149
var (
148150
ctx = r.Context()

‎coderd/templateversions.go

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -911,6 +911,8 @@ func (api *API) patchActiveTemplateVersion(rw http.ResponseWriter, r *http.Reque
911911
})
912912
}
913913

914+
// postTemplateVersionsByOrganization creates a new version of a template. An import job is queued to parse the storage method provided.
915+
//
914916
// @Summary Create template version by organization
915917
// @ID create-template-version-by-organization
916918
// @Security CoderSessionToken
@@ -921,8 +923,6 @@ func (api *API) patchActiveTemplateVersion(rw http.ResponseWriter, r *http.Reque
921923
// @Param request body codersdk.CreateTemplateVersionDryRunRequest true "Create template version request"
922924
// @Success 201 {object} codersdk.TemplateVersion
923925
// @Router /organizations/{organization}/templateversions [post]
924-
//
925-
// postTemplateVersionsByOrganization creates a new version of a template. An import job is queued to parse the storage method provided.
926926
func (api *API) postTemplateVersionsByOrganization(rw http.ResponseWriter, r *http.Request) {
927927
var (
928928
ctx = r.Context()
@@ -1207,6 +1207,12 @@ func (api *API) postTemplateVersionsByOrganization(rw http.ResponseWriter, r *ht
12071207
httpapi.Write(ctx, rw, http.StatusCreated, convertTemplateVersion(templateVersion, convertProvisionerJob(provisionerJob), user))
12081208
}
12091209

1210+
// templateVersionResources returns the workspace agent resources associated
1211+
// with a template version. A template can specify more than one resource to be
1212+
// provisioned, each resource can have an agent that dials back to coderd. The
1213+
// agents returned are informative of the template version, and do not return
1214+
// agents associated with any particular workspace.
1215+
//
12101216
// @Summary Get resources by template version
12111217
// @ID get-resources-by-template-version
12121218
// @Security CoderSessionToken
@@ -1215,12 +1221,6 @@ func (api *API) postTemplateVersionsByOrganization(rw http.ResponseWriter, r *ht
12151221
// @Param templateversion path string true "Template version ID" format(uuid)
12161222
// @Success 200 {array} codersdk.WorkspaceResource
12171223
// @Router /templateversions/{templateversion}/resources [get]
1218-
//
1219-
// templateVersionResources returns the workspace agent resources associated
1220-
// with a template version. A template can specify more than one resource to be
1221-
// provisioned, each resource can have an agent that dials back to coderd. The
1222-
// agents returned are informative of the template version, and do not return
1223-
// agents associated with any particular workspace.
12241224
func (api *API) templateVersionResources(rw http.ResponseWriter, r *http.Request) {
12251225
var (
12261226
ctx = r.Context()
@@ -1244,6 +1244,11 @@ func (api *API) templateVersionResources(rw http.ResponseWriter, r *http.Request
12441244
api.provisionerJobResources(rw, r, job)
12451245
}
12461246

1247+
// templateVersionLogs returns the logs returned by the provisioner for the given
1248+
// template version. These logs are only associated with the template version,
1249+
// and not any build logs for a workspace.
1250+
// Eg: Logs returned from 'terraform plan' when uploading a new terraform file.
1251+
//
12471252
// @Summary Get logs by template version
12481253
// @ID get-logs-by-template-version
12491254
// @Security CoderSessionToken
@@ -1255,11 +1260,6 @@ func (api *API) templateVersionResources(rw http.ResponseWriter, r *http.Request
12551260
// @Param follow query bool false "Follow log stream"
12561261
// @Success 200 {array} codersdk.ProvisionerJobLog
12571262
// @Router /templateversions/{templateversion}/logs [get]
1258-
//
1259-
// templateVersionLogs returns the logs returned by the provisioner for the given
1260-
// template version. These logs are only associated with the template version,
1261-
// and not any build logs for a workspace.
1262-
// Eg: Logs returned from 'terraform plan' when uploading a new terraform file.
12631263
func (api *API) templateVersionLogs(rw http.ResponseWriter, r *http.Request) {
12641264
var (
12651265
ctx = r.Context()

‎coderd/workspaceapps.go

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -614,20 +614,20 @@ func (api *API) setWorkspaceAppCookie(rw http.ResponseWriter, r *http.Request, t
614614
return true
615615
}
616616

617+
// workspaceApplicationAuth is an endpoint on the main router that handles
618+
// redirects from the subdomain handler.
619+
//
620+
// This endpoint is under /api so we don't return the friendly error page here.
621+
// Any errors on this endpoint should be errors that are unlikely to happen
622+
// in production unless the user messes with the URL.
623+
//
617624
// @Summary Redirect to URI with encrypted API key
618625
// @ID redirect-to-uri-with-encrypted-api-key
619626
// @Security CoderSessionToken
620627
// @Tags Applications
621628
// @Param redirect_uri query string false "Redirect destination"
622629
// @Success 307
623630
// @Router /applications/auth-redirect [get]
624-
//
625-
// workspaceApplicationAuth is an endpoint on the main router that handles
626-
// redirects from the subdomain handler.
627-
//
628-
// This endpoint is under /api so we don't return the friendly error page here.
629-
// Any errors on this endpoint should be errors that are unlikely to happen
630-
// in production unless the user messes with the URL.
631631
func (api *API) workspaceApplicationAuth(rw http.ResponseWriter, r *http.Request) {
632632
ctx := r.Context()
633633
if api.AppHostname == "" {

‎coderd/workspaceresourceauth.go

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@ func (api *API) postWorkspaceAuthAzureInstanceIdentity(rw http.ResponseWriter, r
4545
api.handleAuthInstanceID(rw, r, instanceID)
4646
}
4747

48+
// AWS supports instance identity verification:
49+
// https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html
50+
// Using this, we can exchange a signed instance payload for an agent token.
51+
//
4852
// @Summary Authenticate agent on AWS instance
4953
// @ID authenticate-agent-on-aws-instance
5054
// @Security CoderSessionToken
@@ -53,10 +57,6 @@ func (api *API) postWorkspaceAuthAzureInstanceIdentity(rw http.ResponseWriter, r
5357
// @Param request body codersdk.AWSInstanceIdentityToken true "Instance identity token"
5458
// @Success 200 {object} codersdk.WorkspaceAgentAuthenticateResponse
5559
// @Router /workspaceagents/aws-instance-identity [post]
56-
//
57-
// AWS supports instance identity verification:
58-
// https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html
59-
// Using this, we can exchange a signed instance payload for an agent token.
6060
func (api *API) postWorkspaceAuthAWSInstanceIdentity(rw http.ResponseWriter, r *http.Request) {
6161
ctx := r.Context()
6262
var req codersdk.AWSInstanceIdentityToken
@@ -74,6 +74,10 @@ func (api *API) postWorkspaceAuthAWSInstanceIdentity(rw http.ResponseWriter, r *
7474
api.handleAuthInstanceID(rw, r, identity.InstanceID)
7575
}
7676

77+
// Google Compute Engine supports instance identity verification:
78+
// https://cloud.google.com/compute/docs/instances/verifying-instance-identity
79+
// Using this, we can exchange a signed instance payload for an agent token.
80+
//
7781
// @Summary Authenticate agent on Google Cloud instance
7882
// @ID authenticate-agent-on-google-cloud-instance
7983
// @Security CoderSessionToken
@@ -82,10 +86,6 @@ func (api *API) postWorkspaceAuthAWSInstanceIdentity(rw http.ResponseWriter, r *
8286
// @Param request body codersdk.GoogleInstanceIdentityToken true "Instance identity token"
8387
// @Success 200 {object} codersdk.WorkspaceAgentAuthenticateResponse
8488
// @Router /workspaceagents/google-instance-identity [post]
85-
//
86-
// Google Compute Engine supports instance identity verification:
87-
// https://cloud.google.com/compute/docs/instances/verifying-instance-identity
88-
// Using this, we can exchange a signed instance payload for an agent token.
8989
func (api *API) postWorkspaceAuthGoogleInstanceIdentity(rw http.ResponseWriter, r *http.Request) {
9090
ctx := r.Context()
9191
var req codersdk.GoogleInstanceIdentityToken

‎coderd/workspaces.go

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,9 @@ func (api *API) workspace(rw http.ResponseWriter, r *http.Request) {
101101
))
102102
}
103103

104+
// workspaces returns all workspaces a user can read.
105+
// Optional filters with query params
106+
//
104107
// @Summary List workspaces
105108
// @ID list-workspaces
106109
// @Security CoderSessionToken
@@ -113,9 +116,6 @@ func (api *API) workspace(rw http.ResponseWriter, r *http.Request) {
113116
// @Param has_agent query string false "Filter by agent status" Enums(connected,connecting,disconnected,timeout)
114117
// @Success 200 {object} codersdk.WorkspacesResponse
115118
// @Router /workspaces [get]
116-
//
117-
// workspaces returns all workspaces a user can read.
118-
// Optional filters with query params
119119
func (api *API) workspaces(rw http.ResponseWriter, r *http.Request) {
120120
ctx := r.Context()
121121
apiKey := httpmw.APIKey(r)
@@ -266,6 +266,8 @@ func (api *API) workspaceByOwnerAndName(rw http.ResponseWriter, r *http.Request)
266266
))
267267
}
268268

269+
// Create a new workspace for the currently authenticated user.
270+
//
269271
// @Summary Create user workspace by organization
270272
// @ID create-user-workspace-by-organization
271273
// @Security CoderSessionToken
@@ -275,8 +277,6 @@ func (api *API) workspaceByOwnerAndName(rw http.ResponseWriter, r *http.Request)
275277
// @Param user path string true "Username, UUID, or me"
276278
// @Success 200 {object} codersdk.Workspace
277279
// @Router /organizations/{organization}/members/{user}/workspaces [post]
278-
//
279-
// Create a new workspace for the currently authenticated user.
280280
func (api *API) postWorkspacesByOrganization(rw http.ResponseWriter, r *http.Request) {
281281
var (
282282
ctx = r.Context()

0 commit comments

Comments
 (0)