From 36b61747ed58dee36773d2d93fb0b489ebb94c34 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Mon, 1 Apr 2024 10:11:22 -0500 Subject: [PATCH 1/2] docs: describe mutually exclusive create workspace template fields Ideally we could do this in the OpenAPI spec, but there is no first class "mutually exclusive" feature in OpenAPI. So in lieu of something more complex, or changing our struct/validation, a description comment should suffice. --- coderd/apidoc/docs.go | 1 + coderd/apidoc/swagger.json | 1 + codersdk/organizations.go | 3 +++ docs/api/schemas.md | 2 ++ 4 files changed, 7 insertions(+) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index a082996d3298c..ab6a1400bb893 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -9045,6 +9045,7 @@ const docTemplate = `{ } }, "codersdk.CreateWorkspaceRequest": { + "description": "CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the latest version of the template will be used.", "type": "object", "required": [ "name" diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index a559938463a2b..f408dbe124a77 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -8052,6 +8052,7 @@ } }, "codersdk.CreateWorkspaceRequest": { + "description": "CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the latest version of the template will be used.", "type": "object", "required": ["name"], "properties": { diff --git a/codersdk/organizations.go b/codersdk/organizations.go index a6a1b927cae48..6f7de745d32fa 100644 --- a/codersdk/organizations.go +++ b/codersdk/organizations.go @@ -138,6 +138,9 @@ type CreateTemplateRequest struct { // CreateWorkspaceRequest provides options for creating a new workspace. // Either TemplateID or TemplateVersionID must be specified. They cannot both be present. +// @Description CreateWorkspaceRequest provides options for creating a new workspace. +// @Description Only one of TemplateID or TemplateVersionID can be specified, not both. +// @Description If TemplateID is specified, the latest version of the template will be used. type CreateWorkspaceRequest struct { // TemplateID specifies which template should be used for creating the workspace. TemplateID uuid.UUID `json:"template_id,omitempty" validate:"required_without=TemplateVersionID,excluded_with=TemplateVersionID" format:"uuid"` diff --git a/docs/api/schemas.md b/docs/api/schemas.md index f46e02a636026..decb5f9b212a1 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -1646,6 +1646,8 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in } ``` +CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the latest version of the template will be used. + ### Properties | Name | Type | Required | Restrictions | Description | From bf22735d43b6e034ba4264a73906effc2e536fd2 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Mon, 1 Apr 2024 10:18:51 -0500 Subject: [PATCH 2/2] chore: Add description to code sample as well --- coderd/apidoc/docs.go | 3 ++- coderd/apidoc/swagger.json | 3 ++- coderd/workspaces.go | 4 ++++ codersdk/organizations.go | 2 +- docs/api/schemas.md | 2 +- docs/api/workspaces.md | 5 +++++ 6 files changed, 15 insertions(+), 4 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index ab6a1400bb893..7bfd521b093ce 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -2211,6 +2211,7 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "description": "Create a new workspace using a template. The request must\nspecify either the Template ID or the Template Version ID,\nnot both. If the Template ID is specified, the active version\nof the template will be used.", "consumes": [ "application/json" ], @@ -9045,7 +9046,7 @@ const docTemplate = `{ } }, "codersdk.CreateWorkspaceRequest": { - "description": "CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the latest version of the template will be used.", + "description": "CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the active version of the template will be used.", "type": "object", "required": [ "name" diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index f408dbe124a77..c4dabcacaf6ba 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -1932,6 +1932,7 @@ "CoderSessionToken": [] } ], + "description": "Create a new workspace using a template. The request must\nspecify either the Template ID or the Template Version ID,\nnot both. If the Template ID is specified, the active version\nof the template will be used.", "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Workspaces"], @@ -8052,7 +8053,7 @@ } }, "codersdk.CreateWorkspaceRequest": { - "description": "CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the latest version of the template will be used.", + "description": "CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the active version of the template will be used.", "type": "object", "required": ["name"], "properties": { diff --git a/coderd/workspaces.go b/coderd/workspaces.go index f29d44d6d75e3..d3456fab00992 100644 --- a/coderd/workspaces.go +++ b/coderd/workspaces.go @@ -332,6 +332,10 @@ func (api *API) workspaceByOwnerAndName(rw http.ResponseWriter, r *http.Request) // Create a new workspace for the currently authenticated user. // // @Summary Create user workspace by organization +// @Description Create a new workspace using a template. The request must +// @Description specify either the Template ID or the Template Version ID, +// @Description not both. If the Template ID is specified, the active version +// @Description of the template will be used. // @ID create-user-workspace-by-organization // @Security CoderSessionToken // @Accept json diff --git a/codersdk/organizations.go b/codersdk/organizations.go index 6f7de745d32fa..cb353dff27cc6 100644 --- a/codersdk/organizations.go +++ b/codersdk/organizations.go @@ -140,7 +140,7 @@ type CreateTemplateRequest struct { // Either TemplateID or TemplateVersionID must be specified. They cannot both be present. // @Description CreateWorkspaceRequest provides options for creating a new workspace. // @Description Only one of TemplateID or TemplateVersionID can be specified, not both. -// @Description If TemplateID is specified, the latest version of the template will be used. +// @Description If TemplateID is specified, the active version of the template will be used. type CreateWorkspaceRequest struct { // TemplateID specifies which template should be used for creating the workspace. TemplateID uuid.UUID `json:"template_id,omitempty" validate:"required_without=TemplateVersionID,excluded_with=TemplateVersionID" format:"uuid"` diff --git a/docs/api/schemas.md b/docs/api/schemas.md index decb5f9b212a1..f0b5646fea240 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -1646,7 +1646,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in } ``` -CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the latest version of the template will be used. +CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the active version of the template will be used. ### Properties diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index c16dd970a5cff..886f8401f7d7e 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -14,6 +14,11 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/member `POST /organizations/{organization}/members/{user}/workspaces` +Create a new workspace using a template. The request must +specify either the Template ID or the Template Version ID, +not both. If the Template ID is specified, the active version +of the template will be used. + > Body parameter ```json