Skip to content

docs: describe the Members API operations and parameters - #31534

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-members
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-members

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This describes the eleven Members routes that had no @Description and improves the thin parameter text on them, so the REST API reference renders more than a title.
The reference comes from swagger.json, which make gen builds from these annotations.

Merge notes

This PR doesn't touch #31473's exemption lists.
If #31473 merges first, TestEndpointsDocumented names each route on this PR to remove from those lists.

Existing text I corrected on routes in this list:

  • user said "User ID, name, or me". httpmw.ExtractUserParam takes an ID, a username, or me, so it now uses the shared wording.
  • organization said "Organization ID", but httpmw.ExtractOrganizationParam also accepts a name and default.

Verification

check_routes.py: summary: need=0 problems=0 thin_params_left=0
go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.392s
go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.484s

A JSON diff of swagger.json against main shows 33 changes, all adding or editing description values on these routes and their parameters, and nothing else.
check_routes.py was run against the fresh list for this branch, which matches the shared list except that it reflects these edits.

doc-check ran in author self-check mode on the branch diff, persona by persona.
The Fact Checker found one wrong claim, which the Skeptic confirmed: GET /api/v2/users/roles said only the Owner and User Admin roles can read role assignments, but the Member role grants assign_role read to every user, so the text now says every user has it.
The Continuity Editor raised one finding, that docs/admin/users/groups-roles.md lists "Change User roles" as Owner only while PUT .../members/{user}/roles names User Admin, and the Skeptic rejected it because the code gives User Admin the assign permission and the docs table is about site roles.
The Copy Editor found nothing.
The fix is in the follow-up commit, and the swagger tests, check_routes.py, and the swagger.json diff were run again.

Claims checked against the code
Route Claim Evidence
POST /api/v2/organizations/{organization}/members/roles, PUT same path, DELETE .../roles/{roleName} Need a Premium license enterprise/coderd/coderd.go:469 (RequireFeatureMW(codersdk.FeatureCustomRoles))
Same three custom role routes Need create, update, or delete permission on organization role assignment, which Owner and Organization Admin have coderd/database/dbauthz/dbauthz.go:6602, :8166, :2426, coderd/rbac/roles.go:414 (Owner), :587 (Organization Admin, all permissions except the listed ones), :657 (Organization User Admin has only assign, unassign, read)
POST .../members/roles Name can't match a built-in role, no site, user, or organization member permissions enterprise/coderd/roles.go:304, :320 to :343
PUT .../members/roles Invalid permissions are dropped without an error enterprise/coderd/roles.go:165 to :167, :276
PUT .../members/roles Updates the role named in the body enterprise/coderd/roles.go:154
GET /api/v2/organizations/{organization}/members/roles Every organization member can read assignable roles, and each role has assignable coderd/roles.go:73, coderd/rbac/roles.go:1188, coderd/roles.go:100 to :118
GET /api/v2/users/roles Needs read on role assignment, which every user has coderd/roles.go:32, coderd/rbac/roles.go:446 to :452 (Member role)
POST .../members/{user} Needs permission to read the user and create organization members coderd/coderd.go:1598 (ExtractUserParam), coderd/database/dbauthz/dbauthz.go:5580, :6749, coderd/rbac/roles.go:547, :659
POST .../members/{user} Fails for OIDC users while organization sync is enabled coderd/members.go:54, :626
POST .../members/{user} Adds the user with no roles of their own coderd/members.go:63 (Roles: []string{})
DELETE .../members/{user} Needs delete permission on organization members coderd/database/dbauthz/dbauthz.go:2668, coderd/rbac/roles.go:547, :659
DELETE .../members/{user} You can't remove yourself coderd/members.go:134
GET .../members/{user}, GET .../members Return only members you can read coderd/database/dbauthz/dbauthz.go:7578 (fetchWithPostFilter)
GET .../paginated-members Needs read on all organization members coderd/database/dbauthz/dbauthz.go:7582, coderd/rbac/roles.go:492, :525, :547, :633, :659, :686
GET .../paginated-members Ordered by username, after_id is a user ID coderd/database/queries/organizationmembers.sql:120, :231
GET .../paginated-members q keys coderd/searchquery/search.go:217 to :231 (searchquery.Users), coderd/members.go:297
GET .../paginated-members limit and offset defaults of 0 coderd/pagination.go:19 to :23 (ParsePagination), coderd/members.go:306
PUT .../members/{user}/roles You can't change your own roles coderd/members.go:451
PUT .../members/{user}/roles Blocked for OIDC users while organization role sync is enabled coderd/members.go:445, :494 to :512
PUT .../members/{user}/roles Replaces the member's roles and needs permission to assign organization roles coderd/database/dbauthz/dbauthz.go:8329, :1431 (canAssignRoles), coderd/rbac/roles.go:538, :657
{user} and {organization} path parameters Accepted forms coderd/httpmw/userparam.go:51 to :110, coderd/httpmw/organizationparam.go:54 to :96
Writing rules applied
  • One to three sentences per route, present tense, first sentence starts with a verb and stands alone.
  • Permission sentences name the built-in roles, traced to dbauthz or Authorize calls and coderd/rbac/roles.go.
  • "Requires a Premium license" appears only on the three custom role routes behind RequireFeatureMW.
  • The deprecated GET .../members route keeps @Deprecated and names its replacement by full path.
  • Shared wording for user, organization, limit, and offset, copied exactly, and a specific after_id because the handler pages by user ID.
  • Body parameters say what the body is, not the request type name.
  • Full API paths and literals in backticks, with no dashes or semicolons.
CI flakes unrelated to this change

test-go-pg (windows-2022) failed TestFailedRecoveryPreservesTranscript/unconfigured, a Coder Agents test that this PR doesn't touch: https://github.com/coder/coder/actions/runs/40926927636/job/123635080199

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

The REST API reference renders these routes from swagger.json, and they
had no description.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Members API operations and parameters. The claims table above still covers that commit.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 30, 2026
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.

1 participant