elastic · lcawl · Jul 30, 2024 · Jul 23, 2024 · Jul 23, 2024 · Jul 23, 2024
diff --git a/oas_docs/makefile b/oas_docs/makefile
@@ -16,12 +16,12 @@
 .PHONY: api-docs
 api-docs: ## Generate kibana.serverless.yaml and kibana.yaml
 	@npx @redocly/cli join "kibana.info.serverless.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml" "../packages/core/saved-objects/docs/openapi/bundled_serverless.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "output/kibana.serverless.yaml" "bundle.serverless.json" --prefix-components-with-info-prop title
-	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
+	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml"  "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
 
 .PHONY: api-docs-stateful
 api-docs-stateful: ## Generate only kibana.yaml
-	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
-# Temporarily omit "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" and "../x-pack/plugins/cases/docs/openapi/bundled.yaml" due to OAS version
+	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
+# Temporarily omit "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" due to OAS version
 # Temporarily omit "../x-pack/plugins/fleet/common/openapi/bundled.yaml" due to internals tag and tag sorting
 
 .PHONY: api-docs-serverless

diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
@@ -13,22 +13,11 @@ A guide about the openApi specification can be found at [https://swagger.io/docs
 
 ## Tools
 
-It is possible to validate the docs before bundling them with the following
-command in the `x-pack/plugins/cases/docs/openapi/` folder:
-
-  ```bash
-    npx swagger-cli validate entrypoint.yaml
-  ```
-
-Then you can generate the `bundled` files by running the following commands:
+Generate the `bundled` files by running the following commands:
 
   ```bash
     npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
     npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
   ```
 
-After generating the json bundle ensure that it is also valid by running the following command:
-
-  ```bash
-     npx @redocly/cli lint bundled.json
-  ```
+Then join these files with the rest of the Kibana APIs per `oas_docs/README.md`
@@ -4,5 +4,4 @@ description: An identifier for the alert.
 required: true
 schema:
   type: string
-  examples:
-    - 09f0c261e39e36351d75995b78bb83673774d1bc2cca9df2d15f0e5c0a99a540
+  example: 09f0c261e39e36351d75995b78bb83673774d1bc2cca9df2d15f0e5c0a99a540
@@ -4,5 +4,4 @@ description: The identifier for the case. To retrieve case IDs, use the find cas
 required: true
 schema:
   type: string
-  examples:
-    - 9c235210-6834-11ea-a78c-6ffb38a34414
+  example: 9c235210-6834-11ea-a78c-6ffb38a34414
@@ -4,9 +4,8 @@ description: Filters the returned cases by category.
 schema:
   oneOf:
     - type: string
+      example: my-category
     - type: array
       items:
         type: string
-      maxItems: 100
-      examples:
-        - [ my-category ]
+      maxItems: 100
@@ -6,5 +6,4 @@ description: >
 required: true 
 schema:
   type: string
-  examples:
-    - '71ec1870-725b-11ea-a0b2-c51ea50a58e2'
+  example: '71ec1870-725b-11ea-a0b2-c51ea50a58e2'
@@ -4,5 +4,4 @@ description: An identifier for the configuration.
 required: true
 schema:
   type: string
-  examples:
-    - 3297a0f0-b5ec-11ec-b141-0fdb20a7f9a9
+  example: 3297a0f0-b5ec-11ec-b141-0fdb20a7f9a9
@@ -4,5 +4,4 @@ description: An identifier for the connector. To retrieve connector IDs, use the
 required: true
 schema:
   type: string
-  examples:
-    - abed3a70-71bd-11ea-a0b2-c51ea50a58e2
+  example: abed3a70-71bd-11ea-a0b2-c51ea50a58e2
@@ -4,5 +4,4 @@ description: he default operator to use for the simple_query_string.
 schema:
   type: string
   default: OR
-  examples:
-    - OR
+example: OR
@@ -5,5 +5,4 @@ description: >
   The date must be specified as a KQL data range or date match expression.
 schema:
   type: string
-  examples:
-    - now-1d
+  example: now-1d
@@ -10,5 +10,4 @@ schema:
     type: string
     minItems: 1
     maxItems: 100
-  examples:
-    - [ d4e7abb0-b462-11ec-9a8d-698504725a43 ]
+example: d4e7abb0-b462-11ec-9a8d-698504725a43
@@ -10,5 +10,4 @@ schema:
     - type: array
       items:
         $ref: '../schemas/owners.yaml'
-      examples:
-        - [ cases ]
+example: cases
@@ -5,5 +5,3 @@ required: false
 schema:
   type: integer
   default: 1
-  examples:
-    - 1
@@ -8,5 +8,4 @@ schema:
       items:
         type: string
       maxItems: 100
-      examples:
-        - [ elastic ]
+example: elastic
@@ -12,5 +12,4 @@ schema:
     - status
     - severity
   default: createdAt
-  examples:
-    - updatedAt
+example: updatedAt
@@ -4,5 +4,4 @@ description: An identifier for the space. If `/s/` and the identifier are omitte
 required: true
 schema:
   type: string
-  examples:
-    - default
+  example: default
@@ -7,5 +7,4 @@ schema:
     - closed
     - in-progress
     - open
-  examples:
-    - open
+example: open
@@ -8,5 +8,4 @@ schema:
       items:
         type: string
       maxItems: 100
-      examples:
-        - [ tag-1 ]
+example: tag-1
@@ -5,5 +5,4 @@ description: >
   The date must be specified as a KQL data range or date match expression.
 schema:
   type: string
-  examples:
-    - now+1d
+example: now+1d
@@ -21,5 +21,4 @@ schema:
       - tags
       - title
       - user
-  examples:
-    - [ create_case ]
+example: create_case
@@ -3,11 +3,9 @@ title: Unsuccessful cases API response
 properties:
   error:
     type: string
-    examples:
-      - Unauthorized
+    example: Unauthorized
   message:
     type: string 
   statusCode:
     type: integer
-    examples:
-      - 401
+    example: 401
@@ -13,5 +13,4 @@ enum:
   - status
   - settings
   - severity
-examples:
-  - create_case
+example: create_case
@@ -5,5 +5,4 @@ enum:
   - delete
   - push_to_service
   - update
-examples:
-  - create
+example: create
@@ -19,7 +19,6 @@ properties:
   type: 
     description: The type of comment.
     type: string
-    examples:
-      - alert
+    example: alert
     enum:
       - alert
@@ -6,15 +6,13 @@ properties:
     description: The new comment. It is required only when `type` is `user`.
     type: string
     maxLength: 30000
-    examples:
-      - A new comment.
+    example: A new comment.
   owner:
     $ref: 'owners.yaml'
   type: 
     type: string
     description: The type of comment.
-    examples:
-      - user
+    example: user
     enum:
       - user
 required:

@@ -7,13 +7,11 @@ properties:
     type: array
     items:
       type: string
-      examples:
-        - a6e12ac4-7bce-457b-84f6-d7ce8deb8446
+      example: a6e12ac4-7bce-457b-84f6-d7ce8deb8446
   created_at:
     type: string
     format: date-time
-    examples:
-      - 2023-11-06T19:29:38.424Z
+    example: 2023-11-06T19:29:38.424Z
   created_by:
     type: object
     required:
@@ -24,52 +22,44 @@ properties:
       $ref: 'user_properties.yaml'
   id:
     type: string
-    examples:
-      - 73362370-ab1a-11ec-985f-97e55adae8b9
+    example: 73362370-ab1a-11ec-985f-97e55adae8b9
   index:
     type: array
     items:
       type: string
-      examples:
-        - .internal.alerts-security.alerts-default-000001
+      example: .internal.alerts-security.alerts-default-000001
   owner:
     $ref: 'owners.yaml'
   pushed_at:
-    type:
-      - "string"
-      - "null"
+    type: string
     format: date-time
-    examples:
-      - null
+    example: null
+    nullable: true
   pushed_by:
-    type:
-      - "object"
-      - "null"
+    type: object
     required:
       - email
       - full_name
       - username
     properties:
       $ref: 'user_properties.yaml'
+    nullable: true
   rule:
     type: object
     properties:
       $ref: 'rule_properties.yaml'
   type:
     type: string
-    examples:
-      - alert
+    example: alert
     enum:
       - alert
   updated_at:
-    type:
-      - "string"
-      - "null"
+    type: string
     format: date-time
+    nullable: true
   updated_by:
-    type:
-      - "object"
-      - "null"
+    type: object
+    nullable: true
     required:
       - email
       - full_name
@@ -78,5 +68,4 @@ properties:
       $ref: 'user_properties.yaml'
   version:
     type: string
-    examples:
-      - WzMwNDgsMV0=
+    example: WzMwNDgsMV0=
@@ -13,5 +13,4 @@ oneOf:
       type: string
     maxItems: 1000
 x-technical-preview: true
-examples:
-  - 6b24c4dc44bc720cfc92797f3d61fff952f2b2627db1fb4f8cc49f4530c4ff42
+example: 6b24c4dc44bc720cfc92797f3d61fff952f2b2627db1fb4f8cc49f4530c4ff42
@@ -1,8 +1,7 @@
-type:
-  - "array"
-  - "null"
+type: array
 description: An array containing users that are assigned to the case.
 maxItems: 10
+nullable: true
 items:
   type: object
   required:
@@ -11,5 +10,4 @@ items:
     uid:
       type: string
       description: A unique identifier for the user profile. These identifiers can be found by using the suggest user profile API.
-      examples:
-        - u_0wpfV1MqYDaXzLtRVY-gLMrddKDEmfz51Fszhj7hWC8_0
+      example: u_0wpfV1MqYDaXzLtRVY-gLMrddKDEmfz51Fszhj7hWC8_0