[EDR Workflows] OpenApi Missing Content - Endpoint Management (#212205)

Part of DW team effort -
elastic/security-team#11804

This PR aligns the property/schema descriptions and examples in
AsciiDocs with OpenAPI schemas. The primary goal of this PR was not to
extend or enhance the documentation but to migrate from one system to
another.

Ascii docs -
https://www.elastic.co/guide/en/kibana/8.17/osquery-manager-api.html
OpenApi generated docs -
https://www.elastic.co/docs/api/doc/kibana/operation/operation-endpointgetactionslist

Changes:

Copied missing property descriptions from AsciiDoc to OpenApi properties
Copied existing AsciiDoc examples for both requests and responses
Fixed falsy query object in some GET requests - in OpenApi it was
defined as an object, not as path query params.

---------

Co-authored-by: kibanamachine <[email protected]>
Co-authored-by: natasha-moore-elastic <[email protected]>

Author: 3 people

oas_docs/output/kibana.serverless.yaml

@@ -16,18 +16,30 @@
 
 import { z } from '@kbn/zod';
 
-import { ListRequestQuery } from './list_metadata.gen';
-import { SuccessResponse } from '../model/schema/common.gen';
+import {
+  Page,
+  PageSize,
+  Kuery,
+  HostStatuses,
+  SortField,
+  SortDirection,
+} from '../model/schema/common.gen';
+import { MetadataListResponse } from './list_metadata.gen';
 
 export type GetEndpointMetadataListRequestQuery = z.infer<
   typeof GetEndpointMetadataListRequestQuery
 >;
 export const GetEndpointMetadataListRequestQuery = z.object({
-  query: ListRequestQuery,
+  page: Page.optional(),
+  pageSize: PageSize.optional(),
+  kuery: Kuery.optional(),
+  hostStatuses: HostStatuses,
+  sortField: SortField.optional(),
+  sortDirection: SortDirection.optional(),
 });
 export type GetEndpointMetadataListRequestQueryInput = z.input<
   typeof GetEndpointMetadataListRequestQuery
 >;
 
 export type GetEndpointMetadataListResponse = z.infer<typeof GetEndpointMetadataListResponse>;
-export const GetEndpointMetadataListResponse = SuccessResponse;
+export const GetEndpointMetadataListResponse = MetadataListResponse;

oas_docs/output/kibana.yaml

@@ -10,18 +10,43 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:
-        - name: query
+        - name: page
+          in: query
+          required: false
+          schema:
+            $ref: '../model/schema/common.schema.yaml#/components/schemas/Page'
+        - name: pageSize
+          in: query
+          required: false
+          schema:
+            $ref: '../model/schema/common.schema.yaml#/components/schemas/PageSize'
+        - name: kuery
+          in: query
+          required: false
+          schema:
+            $ref: '../model/schema/common.schema.yaml#/components/schemas/Kuery'
+        - name: hostStatuses
           in: query
           required: true
           schema:
-            $ref: './list_metadata.schema.yaml#/components/schemas/ListRequestQuery'
+            $ref: '../model/schema/common.schema.yaml#/components/schemas/HostStatuses'
+        - name: sortField
+          in: query
+          required: false
+          schema:
+            $ref: '../model/schema/common.schema.yaml#/components/schemas/SortField'
+        - name: sortDirection
+          in: query
+          required: false
+          schema:
+            $ref: '../model/schema/common.schema.yaml#/components/schemas/SortDirection'
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
-                $ref: '../model/schema/common.schema.yaml#/components/schemas/SuccessResponse'
+                $ref: './list_metadata.schema.yaml#/components/schemas/MetadataListResponse'
 
   /internal/api/endpoint/metadata/transforms:
     get:
@@ -50,10 +75,11 @@ paths:
           required: true
           schema:
             type: string
+            example: 'ed518850-681a-4d60-bb98-e22640cae2a8'
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
-                $ref: '../model/schema/common.schema.yaml#/components/schemas/SuccessResponse'
+                $ref: './list_metadata.schema.yaml#/components/schemas/EndpointMetadataResponse'

x-pack/solutions/security/plugins/security_solution/common/api/endpoint/metadata/get_metadata.gen.ts

@@ -16,30 +16,8 @@
 
 import { z } from '@kbn/zod';
 
-export type ListRequestQuery = z.infer<typeof ListRequestQuery>;
-export const ListRequestQuery = z.object({
-  /**
-   * Page number
-   */
-  page: z.number().int().min(0).optional().default(0),
-  /**
-   * Number of items per page
-   */
-  pageSize: z.number().int().min(1).max(10000).optional().default(10),
-  kuery: z.string().nullable().optional(),
-  sortField: z
-    .enum([
-      'enrolled_at',
-      'metadata.host.hostname',
-      'host_status',
-      'metadata.Endpoint.policy.applied.name',
-      'metadata.Endpoint.policy.applied.status',
-      'metadata.host.os.name',
-      'metadata.host.ip',
-      'metadata.agent.version',
-      'last_checkin',
-    ])
-    .optional(),
-  sortDirection: z.enum(['asc', 'desc']).nullable().optional(),
-  hostStatuses: z.array(z.enum(['healthy', 'offline', 'updating', 'inactive', 'unenrolled'])),
-});
+export type EndpointMetadataResponse = z.infer<typeof EndpointMetadataResponse>;
+export const EndpointMetadataResponse = z.object({});
+
+export type MetadataListResponse = z.infer<typeof MetadataListResponse>;
+export const MetadataListResponse = z.object({});