[monitors] Deprecate locked property and clarify documentation for restricted_roles

.apigentools-info

@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.2",
-            "regenerated": "2022-03-15 09:31:12.853869",
-            "spec_repo_commit": "80288098"
+            "regenerated": "2022-03-16 14:22:15.397892",
+            "spec_repo_commit": "a7afd4c8"
         },
         "v2": {
             "apigentools_version": "1.6.2",
-            "regenerated": "2022-03-15 09:31:12.864935",
-            "spec_repo_commit": "80288098"
+            "regenerated": "2022-03-16 14:22:15.412827",
+            "spec_repo_commit": "a7afd4c8"
         }
     }
 }

.generator/schemas/v1/openapi.yaml

@@ -5619,8 +5619,12 @@ components:
           example: avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100
           type: string
         restricted_roles:
-          description: A list of role identifiers that can be pulled from the Roles
-            API. Cannot be used with `locked` option.
+          description: A list of unique role identifiers to define which roles are
+            allowed to edit the monitor. Editing a monitor includes any updates to
+            the monitor configuration, monitor deletion, and muting of the monitor
+            for any amount of time. Roles unique identifiers can be pulled from the
+            [Roles API](https://docs.datadoghq.com/api/latest/roles/#list-roles) in
+            the `data.id` field.
           items:
             description: A role UUID.
             type: string
@@ -5945,8 +5949,9 @@ components:
             - If `False`, `[Triggered] Monitor Title`'
           type: boolean
         locked:
+          deprecated: true
           description: Whether or not the monitor is locked (only editable by creator
-            and admins).
+            and admins). Use `restricted_roles` instead.
           type: boolean
         min_failure_duration:
           default: 0
@@ -6553,8 +6558,12 @@ components:
           description: The monitor query.
           type: string
         restricted_roles:
-          description: A list of role identifiers that can be pulled from the Roles
-            API. Cannot be used with `locked` option.
+          description: A list of unique role identifiers to define which roles are
+            allowed to edit the monitor. Editing a monitor includes any updates to
+            the monitor configuration, monitor deletion, and muting of the monitor
+            for any amount of time. Roles unique identifiers can be pulled from the
+            [Roles API](https://docs.datadoghq.com/api/latest/roles/#list-roles) in
+            the `data.id` field.
           items:
             description: A role UUID.
             type: string

.generator/schemas/v2/openapi.yaml

@@ -255,7 +255,7 @@ components:
         format: int64
         type: integer
     RoleID:
-      description: The ID of the role.
+      description: The unique identifier of the role.
       in: path
       name: role_id
       required: true
@@ -4851,7 +4851,7 @@ components:
       description: Relationship to role object.
       properties:
         id:
-          description: ID of the role.
+          description: The unique identifier of the role.
           example: 3653d3c6-0c75-11ea-ad28-fb5701eabc7d
           type: string
         type:
@@ -4861,7 +4861,7 @@ components:
       description: Relationship to roles.
       properties:
         data:
-          description: An array containing type and ID of a role.
+          description: An array containing type and the unique identifier of a role.
           items:
             $ref: '#/components/schemas/RelationshipToRoleData'
           type: array
@@ -4934,7 +4934,7 @@ components:
         attributes:
           $ref: '#/components/schemas/RoleAttributes'
         id:
-          description: ID of the role.
+          description: The unique identifier of the role.
           type: string
         relationships:
           $ref: '#/components/schemas/RoleResponseRelationships'
@@ -4957,7 +4957,8 @@ components:
           readOnly: true
           type: string
         name:
-          description: Name of the role.
+          description: The name of the role. The name is neither unique nor a stable
+            identifier of the role.
           type: string
         user_count:
           description: Number of users with that role.
@@ -5047,7 +5048,7 @@ components:
         attributes:
           $ref: '#/components/schemas/RoleCreateAttributes'
         id:
-          description: ID of the role.
+          description: The unique identifier of the role.
           type: string
         relationships:
           $ref: '#/components/schemas/RoleResponseRelationships'
@@ -5099,7 +5100,7 @@ components:
         attributes:
           $ref: '#/components/schemas/RoleUpdateAttributes'
         id:
-          description: ID of the role.
+          description: The unique identifier of the role.
           example: 00000000-0000-1111-0000-000000000000
           type: string
         type:
@@ -5129,7 +5130,7 @@ components:
         attributes:
           $ref: '#/components/schemas/RoleUpdateAttributes'
         id:
-          description: ID of the role.
+          description: The unique identifier of the role.
           type: string
         relationships:
           $ref: '#/components/schemas/RoleResponseRelationships'
@@ -9437,7 +9438,7 @@ paths:
         type: safe
   /api/v2/roles:
     get:
-      description: Returns all roles, including their names and IDs.
+      description: Returns all roles, including their names and their unique identifiers.
       operationId: ListRoles
       parameters:
       - $ref: '#/components/parameters/PageSize'