WIP

coder · mtojek · Dec 21, 2022 · Dec 20, 2022 · Dec 20, 2022 · Dec 20, 2022
commit 9950d35b41ecc8a6856818dc747be03b83b6964f
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
@@ -716,7 +716,6 @@ const docTemplate = `{
             "type": "object",
             "properties": {
                 "action": {
-                    "description": "Action can be ` + "`" + `create` + "`" + `, ` + "`" + `read` + "`" + `, ` + "`" + `update` + "`" + `, or ` + "`" + `delete` + "`" + `",
                     "type": "string",
                     "enum": [
                         "create",
@@ -726,7 +725,7 @@ const docTemplate = `{
                     ]
                 },
                 "object": {
-                    "description": "Object can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.",
+                    "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.",
                     "$ref": "#/definitions/codersdk.AuthorizationObject"
                 }
             }

diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
@@ -637,12 +637,11 @@
       "type": "object",
       "properties": {
         "action": {
-          "description": "Action can be `create`, `read`, `update`, or `delete`",
           "type": "string",
           "enum": ["create", "read", "update", "delete"]
         },
         "object": {
-          "description": "Object can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.",
+          "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.",
           "$ref": "#/definitions/codersdk.AuthorizationObject"
         }
       }

diff --git a/codersdk/authorization.go b/codersdk/authorization.go
@@ -23,18 +23,20 @@ type AuthorizationRequest struct {
 // AuthorizationCheck is used to check if the currently authenticated user (or
 // the specified user) can do a given action to a given set of objects.
 type AuthorizationCheck struct {
-	// Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.
+	// Object can represent a "set" of objects, such as:
+	//	- All workspaces in an organization
+	//	- All workspaces owned by me
+	//	- All workspaces across the entire product
+	// When defining an object, use the most specific language when possible to
+	// produce the smallest set. Meaning to set as many fields on 'Object' as
+	// you can. Example, if you want to check if you can update all workspaces
+	// owned by 'me', try to also add an 'OrganizationID' to the settings.
+	// Omitting the 'OrganizationID' could produce the incorrect value, as
+	// workspaces have both `user` and `organization` owners.
 	Object AuthorizationObject `json:"object"`
-	// Action can be `create`, `read`, `update`, or `delete`
-	Action string `json:"action" enums:"create,read,update,delete"`
+	Action string              `json:"action" enums:"create,read,update,delete"`
 }
 
-// AuthorizationObject: when defining, use the most specific language when possible to
-// produce the smallest set. Meaning to set as many fields on `Object` as
-// you can. Example, if you want to check if you can update all workspaces
-// owned by `me`, try to also add an `OrganizationID` to the settings.
-// Omitting the `OrganizationID` could produce the incorrect value, as
-// workspaces have both `user` and `organization` owners.
 type AuthorizationObject struct {
 	// ResourceType is the name of the resource.
 	// `./coderd/rbac/object.go` has the list of valid resource types.

diff --git a/docs/api/schemas.md b/docs/api/schemas.md
@@ -18,10 +18,10 @@
 
 ### Properties
 
-| Name     | Type                                                         | Required | Restrictions | Description                                           |
-| -------- | ------------------------------------------------------------ | -------- | ------------ | ----------------------------------------------------- |
-| `action` | string                                                       | false    | none         | Action can be `create`, `read`, `update`, or `delete` |
-| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false    | none         | none                                                  |
+| Name     | Type                                                         | Required | Restrictions | Description |
+| -------- | ------------------------------------------------------------ | -------- | ------------ | ----------- |
+| `action` | string                                                       | false    | none         | none        |
+| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false    | none         | none        |
 
 #### Enumerated Values