Skip to content

docs: describe the PortSharing API operations and parameters - #31549

Closed
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-portsharing
Closed

nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-portsharing

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds descriptions for the 3 PortSharing routes and improves 5 of their parameters.
The 3 workspace path parameters stay as "Workspace ID." because they accept only a UUID.
The REST API reference renders these routes from swagger.json, and they had no description.

Merge notes

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

Verification

summary: need=3 problems=0 thin_params_left=3
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.885s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.508s

A JSON diff of coderd/apidoc/swagger.json against origin/main changes only description values on the routes in this PR.

Claims checked against the code
Route Claim Evidence
GET /api/v2/workspaces/{workspace}/port-share Requires permission to read the workspace, which the workspace owner and the Owner role have; shares ordered by port coderd/database/dbauthz/dbauthz.go:7476-7488, coderd/workspaceagentportshare.go:132-140, coderd/rbac/roles.go:235-244,425
POST /api/v2/workspaces/{workspace}/port-share Requires permission to update the workspace coderd/database/dbauthz/dbauthz.go:9895-9905, coderd/rbac/roles.go:235-244,425
POST /api/v2/workspaces/{workspace}/port-share Port 9 to 65535; share_level authenticated, organization, or public (owner is rejected); protocol http or https; agent must exist in the latest build coderd/workspaceagentportshare.go:37-102, codersdk/workspaceagentportshare.go:54-58,104-107
POST /api/v2/workspaces/{workspace}/port-share With a Premium license (control_shared_ports feature) the template's max_port_share_level limits allowed levels; without it any level is allowed enterprise/coderd/coderd.go:1190-1196, enterprise/coderd/portsharing/portsharing.go:15-18, coderd/portsharing/portsharing.go:16-18
DELETE /api/v2/workspaces/{workspace}/port-share Requires permission to update the workspace; 404 if the share doesn't exist coderd/database/dbauthz/dbauthz.go:2865-2877, coderd/workspaceagentportshare.go:158-175
all three workspace is a UUID only coderd/httpmw/workspaceparam.go:30
doc-check self-check

Ran in author self-check mode on the branch diff, annotation text only: Fact Checker, Continuity Editor, Copy Editor, and then the Skeptic.
The other personas didn't run because no Markdown page was written by hand, and docs/reference/api/ is generated.
Fact Checker: No findings.
The port range, accepted levels and protocols, the Premium-only max_port_share_level limit, and the 404 on delete match coderd/workspaceagentportshare.go and enterprise/coderd/portsharing/portsharing.go.
Continuity Editor: No findings.
The three workspace parameters share one wording.
Copy Editor: No findings that block.
Two non-blocking suggestions are left as they are.
Skeptic: kept 0 and rejected 2.
One finding that the upsert permission sentence runs past 25 words, rejected because the style guide's sentence length is a target and the sentence needs the length to stay precise.
One finding that the request body text says "as described above", rejected as a judgment call with no cited rule, which never blocks.
No blocking findings remain.

Writing rules applied
  • One to three present-tense, active-voice sentences, addressed to "you", with the first sentence starting with a verb.
  • Permission sentences name the built-in roles by display name, each traced to coderd/rbac/roles.go and the handler or dbauthz check.
  • Premium license, experiment, and authentication sentences appear only where the code gates the route.
  • Streams say that the route upgrades to a WebSocket and what each message carries.
  • Full API paths and exact field names, parameter names, and values are in backticks.
  • Parameter text states what the value selects, its accepted forms, and its default and limits from the code.
  • Shared parameters (user, limit, offset) use the shared wording only where the handler matches it.
  • No em dashes, en dashes, spaced double hyphens, semicolons in prose, or raw angle brackets and braces outside backticks.

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

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the PortSharing 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