- Notifications
You must be signed in to change notification settings - Fork928
docs: API users#5620
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
docs: API users#5620
Uh oh!
There was an error while loading.Please reload this page.
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Super, nice job!
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
| // @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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I recently learned aboutswag fmt.
go run github.com/swaggo/swag/cmd/swag@latest fmt --dir ./coderdShould 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:
//@SummaryGet audit logs//@IDget-audit-logs//@SecurityCoderSessionToken//@Producejson//@TagsAudit//@Paramqquerystringtrue"Search query"//@Paramafter_idquerystringfalse"After ID"format(uuid)//@Paramlimitqueryintfalse"Page limit"//@Paramoffsetqueryintfalse"Page offset"//@Success200{object}codersdk.AuditLogResponse//@Router/audit [get]
go fmt:
// @SummaryGet audit logs// @IDget-audit-logs// @SecurityCoderSessionToken// @Producejson// @TagsAudit// @Paramqquerystringtrue"Search query"// @Paramafter_idquerystringfalse"After ID"format(uuid)// @Paramlimitqueryintfalse"Page limit"// @Paramoffsetqueryintfalse"Page offset"// @Success200{object}codersdk.AuditLogResponse// @Router/audit [get]
(Notice tab prefix -> space.)
However, with a comment it's fine.
// Get audit logs.////@SummaryGet audit logs//@IDget-audit-logs//@SecurityCoderSessionToken//@Producejson//@TagsAudit//@Paramqquerystringtrue"Search query"//@Paramafter_idquerystringfalse"After ID"format(uuid)//@Paramlimitqueryintfalse"Page limit"//@Paramoffsetqueryintfalse"Page offset"//@Success200{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 toswaggo/swag to use space indentation for everythingexcept 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Uh oh!
There was an error while loading.Please reload this page.
Related:#3522
Blocker:#5546 (this PR is built on top of that branch)
Changes: