From ef836de330ed5fbec0f3d362acb2a13742ebbb0f Mon Sep 17 00:00:00 2001 From: Colin Adler Date: Mon, 10 Jul 2023 13:57:09 -0500 Subject: [PATCH] fix: document workspace filter query param correctly (#8408) --- coderd/apidoc/docs.go | 51 ++++++-------------------------------- coderd/apidoc/swagger.json | 46 ++++++---------------------------- coderd/workspaces.go | 9 +++---- docs/api/workspaces.md | 31 ++++------------------- 4 files changed, 24 insertions(+), 113 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 844069c006..2f2dff20b5 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -5396,55 +5396,20 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "Filter by owner username", - "name": "owner", + "description": "Search query in the format ` + "`" + `key:value` + "`" + `. Available keys are: owner, template, name, status, has-agent, deleting_by.", + "name": "q", "in": "query" }, { - "type": "string", - "description": "Filter by template name", - "name": "template", + "type": "integer", + "description": "Page limit", + "name": "limit", "in": "query" }, { - "type": "string", - "description": "Filter with partial-match by workspace name", - "name": "name", - "in": "query" - }, - { - "enum": [ - "pending", - "running", - "stopping", - "stopped", - "failed", - "canceling", - "canceled", - "deleted", - "deleting" - ], - "type": "string", - "description": "Filter by workspace status", - "name": "status", - "in": "query" - }, - { - "enum": [ - "connected", - "connecting", - "disconnected", - "timeout" - ], - "type": "string", - "description": "Filter by agent status", - "name": "has_agent", - "in": "query" - }, - { - "type": "string", - "description": "Filter workspaces scheduled to be deleted by this time", - "name": "deleting_by", + "type": "integer", + "description": "Page offset", + "name": "offset", "in": "query" } ], diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 3a9f826aef..a772ce56f4 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -4752,50 +4752,20 @@ "parameters": [ { "type": "string", - "description": "Filter by owner username", - "name": "owner", + "description": "Search query in the format `key:value`. Available keys are: owner, template, name, status, has-agent, deleting_by.", + "name": "q", "in": "query" }, { - "type": "string", - "description": "Filter by template name", - "name": "template", + "type": "integer", + "description": "Page limit", + "name": "limit", "in": "query" }, { - "type": "string", - "description": "Filter with partial-match by workspace name", - "name": "name", - "in": "query" - }, - { - "enum": [ - "pending", - "running", - "stopping", - "stopped", - "failed", - "canceling", - "canceled", - "deleted", - "deleting" - ], - "type": "string", - "description": "Filter by workspace status", - "name": "status", - "in": "query" - }, - { - "enum": ["connected", "connecting", "disconnected", "timeout"], - "type": "string", - "description": "Filter by agent status", - "name": "has_agent", - "in": "query" - }, - { - "type": "string", - "description": "Filter workspaces scheduled to be deleted by this time", - "name": "deleting_by", + "type": "integer", + "description": "Page offset", + "name": "offset", "in": "query" } ], diff --git a/coderd/workspaces.go b/coderd/workspaces.go index 8324d0afae..bf77a73fee 100644 --- a/coderd/workspaces.go +++ b/coderd/workspaces.go @@ -102,12 +102,9 @@ func (api *API) workspace(rw http.ResponseWriter, r *http.Request) { // @Security CoderSessionToken // @Produce json // @Tags Workspaces -// @Param owner query string false "Filter by owner username" -// @Param template query string false "Filter by template name" -// @Param name query string false "Filter with partial-match by workspace name" -// @Param status query string false "Filter by workspace status" Enums(pending,running,stopping,stopped,failed,canceling,canceled,deleted,deleting) -// @Param has_agent query string false "Filter by agent status" Enums(connected,connecting,disconnected,timeout) -// @Param deleting_by query string false "Filter workspaces scheduled to be deleted by this time" +// @Param q query string false "Search query in the format `key:value`. Available keys are: owner, template, name, status, has-agent, deleting_by." +// @Param limit query int false "Page limit" +// @Param offset query int false "Page offset" // @Success 200 {object} codersdk.WorkspacesResponse // @Router /workspaces [get] func (api *API) workspaces(rw http.ResponseWriter, r *http.Request) { diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index 65a399b0e5..42f317616e 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -409,32 +409,11 @@ curl -X GET http://coder-server:8080/api/v2/workspaces \ ### Parameters -| Name | In | Type | Required | Description | -| ------------- | ----- | ------ | -------- | ------------------------------------------------------ | -| `owner` | query | string | false | Filter by owner username | -| `template` | query | string | false | Filter by template name | -| `name` | query | string | false | Filter with partial-match by workspace name | -| `status` | query | string | false | Filter by workspace status | -| `has_agent` | query | string | false | Filter by agent status | -| `deleting_by` | query | string | false | Filter workspaces scheduled to be deleted by this time | - -#### Enumerated Values - -| Parameter | Value | -| ----------- | -------------- | -| `status` | `pending` | -| `status` | `running` | -| `status` | `stopping` | -| `status` | `stopped` | -| `status` | `failed` | -| `status` | `canceling` | -| `status` | `canceled` | -| `status` | `deleted` | -| `status` | `deleting` | -| `has_agent` | `connected` | -| `has_agent` | `connecting` | -| `has_agent` | `disconnected` | -| `has_agent` | `timeout` | +| Name | In | Type | Required | Description | +| -------- | ----- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `q` | query | string | false | Search query in the format `key:value`. Available keys are: owner, template, name, status, has-agent, deleting_by. | +| `limit` | query | integer | false | Page limit | +| `offset` | query | integer | false | Page offset | ### Example responses