docs: API users #5620
docs: API users #5620
Conversation
| // @Param user path string true "User ID, name, or me" | ||
| // @Param request body codersdk.CreateTokenRequest true "Create token request" | ||
| // @Success 201 {object} codersdk.GenerateAPIKeyResponse | ||
| // @Router /users/{user}/keys/tokens [post] |
There was a problem hiding this comment.
I recently learned about swag fmt.
go run github.com/swaggo/swag/cmd/swag@latest fmt --dir ./coderd
Should we enable it for our repo? It's pretty fast.
One gotcha though: Every function needs a proper comment body or go fmt will undo some of the changes.
Example:
swag fmt:
// @Summary Get audit logs
// @ID get-audit-logs
// @Security CoderSessionToken
// @Produce json
// @Tags Audit
// @Param q query string true "Search query"
// @Param after_id query string false "After ID" format(uuid)
// @Param limit query int false "Page limit"
// @Param offset query int false "Page offset"
// @Success 200 {object} codersdk.AuditLogResponse
// @Router /audit [get]go fmt:
// @Summary Get audit logs
// @ID get-audit-logs
// @Security CoderSessionToken
// @Produce json
// @Tags Audit
// @Param q query string true "Search query"
// @Param after_id query string false "After ID" format(uuid)
// @Param limit query int false "Page limit"
// @Param offset query int false "Page offset"
// @Success 200 {object} codersdk.AuditLogResponse
// @Router /audit [get](Notice tab prefix -> space.)
However, with a comment it's fine.
// Get audit logs.
//
// @Summary Get audit logs
// @ID get-audit-logs
// @Security CoderSessionToken
// @Produce json
// @Tags Audit
// @Param q query string true "Search query"
// @Param after_id query string false "After ID" format(uuid)
// @Param limit query int false "Page limit"
// @Param offset query int false "Page offset"
// @Success 200 {object} codersdk.AuditLogResponse
// @Router /audit [get]I dislike the full-on tab indentation though (will be messy for different settings of editor indentation display). We could submit a PR to swaggo/swag to use space indentation for everything except the prefix. Related PR that changed the behavior: swaggo/swag#1386 from all space to all tab (vs just fixing the prefix).
There was a problem hiding this comment.
I can enable it in a separate PR to cover all changes, but I'm concerned if it doesn't conflict with the project formatter.
Related: #3522
Blocker: #5546 (this PR is built on top of that branch)
Changes: