Adjust mechanism for deprecating enum values

Signed-off-by: Thomas Farr <[email protected]>

DEVELOPER_GUIDE.md

@@ -146,7 +146,6 @@ This repository includes several OpenAPI Specification Extensions to fill in any
 - `x-ignorable`: Denotes that the operation should be ignored by the client generator. This is used in operation groups where some operations have been replaced by newer ones, but we still keep them in the specs because the server still supports them.
 - `x-global`: Denotes that the parameter is a global parameter that is included in every operation. These parameters are listed in the [spec/_global_parameters.yaml](spec/_global_parameters.yaml).
 - `x-default`: Contains the default value of a parameter. This is often used to override the default value specified in the schema, or to avoid accidentally changing the default value when updating a shared schema.
-- `x-deprecated-enums`: Contains the values of an enum which should be annotated as deprecated in the client.
 - `x-distributions-included`: Contains a list of distributions known to include the API.
 - `x-distributions-excluded`: Contains a list of distributions known to exclude the API.
 

spec/schemas/_common.yaml

@@ -1924,25 +1924,32 @@ components:
       items:
         $ref: '#/components/schemas/NodeRole'
     NodeRole:
-      type: string
-      enum:
-        - client
-        - cluster_manager
-        - coordinating_only
-        - data
-        - data_cold
-        - data_content
-        - data_frozen
-        - data_hot
-        - data_warm
-        - ingest
-        - master
-        - ml
-        - remote_cluster_client
-        - transform
-        - voting_only
-      x-deprecated-enums:
-        - master
+      oneOf:
+        - type: string
+          enum:
+            - client
+            - coordinating_only
+            - data
+            - data_cold
+            - data_content
+            - data_frozen
+            - data_hot
+            - data_warm
+            - ingest
+            - ml
+            - remote_cluster_client
+            - transform
+            - voting_only
+        - type: string
+          enum:
+            - master
+          deprecated: true
+          x-version-deprecated: '2.0'
+          x-deprecation-message: To promote inclusive language, use 'cluster_manager' instead.
+        - type: string
+          enum:
+            - cluster_manager
+          x-version-added: '2.0'
     HttpHeaders:
       type: object
       additionalProperties:

tests/default/tasks/list.yaml

@@ -0,0 +1,25 @@
+$schema: ../../../json_schemas/test_story.schema.yaml
+
+description: Test tasks list endpoint.
+chapters:
+  - synopsis: List tasks grouped by node.
+    path: /_tasks
+    method: GET
+    parameters:
+      group_by: node
+    response:
+      status: 200
+  - synopsis: List tasks grouped by parent.
+    path: /_tasks
+    method: GET
+    parameters:
+      group_by: parent
+    response:
+      status: 200
+  - synopsis: List tasks grouped by none.
+    path: /_tasks
+    method: GET
+    parameters:
+      group_by: none
+    response:
+      status: 200