Skip to content

feat: Add more swagger checks #5707

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 13, 2023
Merged

feat: Add more swagger checks #5707

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6d21862
Produce: json
mtojek Jan 13, 2023
415e34e
Unique annotations
mtojek Jan 13, 2023
9aa0158
FIX
mtojek Jan 13, 2023
b042dd0
Typo
mtojek Jan 13, 2023
a84303d
Extra check
mtojek Jan 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions coderd/coderdtest/swagger_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ func TestEndpointsDocumented(t *testing.T) {

swaggerComments, err := coderdtest.ParseSwaggerComments("..")
require.NoError(t, err, "can't parse swagger comments")
require.NotEmpty(t, swaggerComments, "swagger comments must be present")

_, _, api := coderdtest.NewWithAPI(t, nil)
coderdtest.VerifySwaggerDefinitions(t, api.APIHandler, swaggerComments)
Expand Down
35 changes: 35 additions & 0 deletions coderd/coderdtest/swaggerparser.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@ func parseSwaggerComment(commentGroup *ast.CommentGroup) SwaggerComment {

func VerifySwaggerDefinitions(t *testing.T, router chi.Router, swaggerComments []SwaggerComment) {
assertUniqueRoutes(t, swaggerComments)
assertSingleAnnotations(t, swaggerComments)

err := chi.Walk(router, func(method, route string, handler http.Handler, middlewares ...func(http.Handler) http.Handler) error {
method = strings.ToLower(method)
Expand Down Expand Up @@ -192,6 +193,36 @@ func assertUniqueRoutes(t *testing.T, comments []SwaggerComment) {
}
}

var uniqueAnnotations = []string{"@ID", "@Summary", "@Tags", "@Router"}

func assertSingleAnnotations(t *testing.T, comments []SwaggerComment) {
for _, comment := range comments {
counters := map[string]int{}

for _, line := range comment.raw {
splitN := strings.SplitN(strings.TrimSpace(line.Text), " ", 3)
if len(splitN) < 2 {
continue // comment prefix without any content
}

if !strings.HasPrefix(splitN[1], "@") {
continue // not a swagger annotation
}

annotation := splitN[1]
if _, ok := counters[annotation]; !ok {
counters[annotation] = 0
}
counters[annotation]++
}

for _, annotation := range uniqueAnnotations {
v := counters[annotation]
assert.Equal(t, 1, v, "%s annotation for route %s must be defined only once", annotation, comment.router)
}
}
}

func findSwaggerCommentByMethodAndRoute(comments []SwaggerComment, method, route string) *SwaggerComment {
for _, c := range comments {
if c.method == method && c.router == route {
Expand Down Expand Up @@ -219,6 +250,7 @@ func assertRequiredAnnotations(t *testing.T, comment SwaggerComment) {
assert.NotEmpty(t, comment.id, "@ID must be defined")
assert.NotEmpty(t, comment.summary, "@Summary must be defined")
assert.NotEmpty(t, comment.tags, "@Tags must be defined")
assert.NotEmpty(t, comment.router, "@Router must be defined")
}

func assertGoCommentFirst(t *testing.T, comment SwaggerComment) {
Expand Down Expand Up @@ -295,6 +327,8 @@ func assertAccept(t *testing.T, comment SwaggerComment) {
}
}

var allowedProduceTypes = []string{"json", "text/event-stream"}

func assertProduce(t *testing.T, comment SwaggerComment) {
var hasResponseModel bool
for _, r := range comment.successes {
Expand All @@ -306,6 +340,7 @@ func assertProduce(t *testing.T, comment SwaggerComment) {

if hasResponseModel {
assert.True(t, comment.produce != "", "Route must have @Produce annotation as it responds with a model structure")
assert.Contains(t, allowedProduceTypes, comment.produce, "@Produce value is limited to specific types: %s", strings.Join(allowedProduceTypes, ","))
} else {
if (comment.router == "/workspaceagents/me/app-health" && comment.method == "post") ||
(comment.router == "/workspaceagents/me/version" && comment.method == "post") ||
Expand Down
4 changes: 2 additions & 2 deletions coderd/workspaceagents.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -826,7 +826,7 @@ func convertWorkspaceAgent(derpMap *tailcfg.DERPMap, coordinator tailnet.Coordin
// @ID submit-workspace-agent-stats
// @Security CoderSessionToken
// @Accept json
// @Produce application/json
// @Produce json
// @Tags Agents
// @Param request body codersdk.AgentStats true "Stats request"
// @Success 200 {object} codersdk.AgentStatsResponse
Expand Down Expand Up @@ -904,7 +904,7 @@ func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Reques
// @ID submit-workspace-agent-application-health
// @Security CoderSessionToken
// @Accept json
// @Produce application/json
// @Produce json
// @Tags Agents
// @Param request body codersdk.PostWorkspaceAppHealthsRequest true "Application health request"
// @Success 200
Expand Down
1 change: 1 addition & 0 deletions enterprise/coderd/coderdenttest/swagger_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ func TestEnterpriseEndpointsDocumented(t *testing.T) {

swaggerComments, err := coderdtest.ParseSwaggerComments("..", "../../../coderd")
require.NoError(t, err, "can't parse swagger comments")
require.NotEmpty(t, swaggerComments, "swagger comments must be present")

_, _, api := coderdenttest.NewWithAPI(t, nil)
coderdtest.VerifySwaggerDefinitions(t, api.AGPL.APIHandler, swaggerComments)
Expand Down