From 4b30dc6ea507ebe48d8c3a641827e50c50d39329 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 5 Jul 2023 10:10:36 -0400 Subject: [PATCH] docs: update template acl example params Param examples were unhelpful --- coderd/apidoc/docs.go | 10 ++++++++++ coderd/apidoc/swagger.json | 10 ++++++++++ codersdk/templates.go | 7 +++++-- docs/api/enterprise.md | 8 ++++---- docs/api/schemas.md | 20 ++++++++++---------- 5 files changed, 39 insertions(+), 16 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 30549de194f23..73d89c0d09a4c 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -9377,15 +9377,25 @@ const docTemplate = `{ "type": "object", "properties": { "group_perms": { + "description": "GroupPerms should be a mapping of group id to role.", "type": "object", "additionalProperties": { "$ref": "#/definitions/codersdk.TemplateRole" + }, + "example": { + "8bd26b20-f3e8-48be-a903-46bb920cf671": "use", + "\u003cuser_id\u003e\u003e": "admin" } }, "user_perms": { + "description": "UserPerms should be a mapping of user id to role. The user id must be the\nuuid of the user, not a username or email address.", "type": "object", "additionalProperties": { "$ref": "#/definitions/codersdk.TemplateRole" + }, + "example": { + "4df59e74-c027-470b-ab4d-cbba8963a5e9": "use", + "\u003cgroup_id\u003e": "admin" } } } diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 78c4249cdea96..fa565cb830eb7 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -8468,15 +8468,25 @@ "type": "object", "properties": { "group_perms": { + "description": "GroupPerms should be a mapping of group id to role.", "type": "object", "additionalProperties": { "$ref": "#/definitions/codersdk.TemplateRole" + }, + "example": { + "8bd26b20-f3e8-48be-a903-46bb920cf671": "use", + "\u003cuser_id\u003e\u003e": "admin" } }, "user_perms": { + "description": "UserPerms should be a mapping of user id to role. The user id must be the\nuuid of the user, not a username or email address.", "type": "object", "additionalProperties": { "$ref": "#/definitions/codersdk.TemplateRole" + }, + "example": { + "4df59e74-c027-470b-ab4d-cbba8963a5e9": "use", + "\u003cgroup_id\u003e": "admin" } } } diff --git a/codersdk/templates.go b/codersdk/templates.go index ee81f99f3106b..b9ed4422763db 100644 --- a/codersdk/templates.go +++ b/codersdk/templates.go @@ -85,8 +85,11 @@ type TemplateUser struct { } type UpdateTemplateACL struct { - UserPerms map[string]TemplateRole `json:"user_perms,omitempty"` - GroupPerms map[string]TemplateRole `json:"group_perms,omitempty"` + // UserPerms should be a mapping of user id to role. The user id must be the + // uuid of the user, not a username or email address. + UserPerms map[string]TemplateRole `json:"user_perms,omitempty" example:":admin,4df59e74-c027-470b-ab4d-cbba8963a5e9:use"` + // GroupPerms should be a mapping of group id to role. + GroupPerms map[string]TemplateRole `json:"group_perms,omitempty" example:">:admin,8bd26b20-f3e8-48be-a903-46bb920cf671:use"` } type UpdateTemplateMeta struct { diff --git a/docs/api/enterprise.md b/docs/api/enterprise.md index 844cef85f9ec5..e459d0ecdf2fa 100644 --- a/docs/api/enterprise.md +++ b/docs/api/enterprise.md @@ -1080,12 +1080,12 @@ curl -X PATCH http://coder-server:8080/api/v2/templates/{template}/acl \ ```json { "group_perms": { - "property1": "admin", - "property2": "admin" + "8bd26b20-f3e8-48be-a903-46bb920cf671": "use", + ">": "admin" }, "user_perms": { - "property1": "admin", - "property2": "admin" + "4df59e74-c027-470b-ab4d-cbba8963a5e9": "use", + "": "admin" } } ``` diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 12a988ee119bb..672ec8bd2a929 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -4441,24 +4441,24 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ```json { "group_perms": { - "property1": "admin", - "property2": "admin" + "8bd26b20-f3e8-48be-a903-46bb920cf671": "use", + ">": "admin" }, "user_perms": { - "property1": "admin", - "property2": "admin" + "4df59e74-c027-470b-ab4d-cbba8963a5e9": "use", + "": "admin" } } ``` ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------------ | ---------------------------------------------- | -------- | ------------ | ----------- | -| `group_perms` | object | false | | | -| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | -| `user_perms` | object | false | | | -| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------ | ---------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| `group_perms` | object | false | | Group perms should be a mapping of group ID to role. | +| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | +| `user_perms` | object | false | | User perms should be a mapping of user ID to role. The user ID must be the uuid of the user, not a username or email address. | +| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | ## codersdk.UpdateUserPasswordRequest