Skip to content

docs: API users - #5620

Merged
mtojek merged 42 commits into
coder:mainfrom
mtojek:3522-organizations-1
Jan 11, 2023
Merged

mtojek merged 42 commits into
coder:mainfrom
mtojek:3522-organizations-1

Conversation

@mtojek

@mtojek mtojek commented Jan 9, 2023 •

Copy link
Copy Markdown
Member

Related: #3522

Blocker: #5546 (this PR is built on top of that branch)

Changes:

  • users

@mtojek mtojek self-assigned this Jan 9, 2023
@mtojek mtojek mentioned this pull request Jan 9, 2023
28 of 29 tasks
@mtojek mtojek changed the title docs: API users, organizations docs: API users Jan 9, 2023
@mtojek mtojek mentioned this pull request Jan 9, 2023
@mtojek
mtojek requested review from bpmct and mafredri January 11, 2023 11:23
@mtojek
mtojek marked this pull request as ready for review January 11, 2023 11:23

@mafredri mafredri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Super, nice job!

Comment thread cli/userstatus_test.go Resolved
Comment thread docs/api/authorization.md Resolved
Comment thread coderd/apikey.go
// @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]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@mtojek mtojek Jan 11, 2023 •

Copy link
Copy Markdown
Member Author

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.

@mtojek
mtojek merged commit 8e9cbdd into coder:main Jan 11, 2023
@github-actions github-actions Bot locked and limited conversation to collaborators Jan 11, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants