[Fleet] Fix Fleet OAS errors

src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json

@@ -1,4 +1,4 @@
 {
-  "./oas_docs/output/kibana.yaml": 448,
-  "./oas_docs/output/kibana.serverless.yaml": 426
+  "./oas_docs/output/kibana.yaml": 268,
+  "./oas_docs/output/kibana.serverless.yaml": 247
 }

x-pack/platform/plugins/shared/fleet/server/routes/epm/examples/post_install_package_by_upload.yaml

@@ -5,6 +5,11 @@ requestBody:
         postInstallByUploadRequestExample:
           description: 'Upload a .zip or .tar.gz package archive (max 100MB)'
           value: '<binary package archive>'
+    application/gzip; application/zip:
+      examples:
+        postInstallByUploadRequestExample:
+          description: 'Upload a .zip or .tar.gz package archive (max 100MB)'
+          value: '<binary package archive>'
 responses:
   200:
     description: 'Successful response'
@@ -19,6 +24,16 @@ responses:
                   type: 'index_template'
               _meta:
                 install_source: 'upload'
+      application/gzip; application/zip:
+        examples:
+          postInstallByUploadExample:
+            description: 'Package successfully installed from upload'
+            value:
+              items:
+                - id: 'my-custom-package-logs-default'
+                  type: 'index_template'
+              _meta:
+                install_source: 'upload'
   400:
     description: 'Bad Request'
     content:
@@ -30,3 +45,11 @@ responses:
               statusCode: 400
               error: 'Bad Request'
               message: 'An error message describing what went wrong'
+      application/gzip; application/zip:
+        examples:
+          genericErrorResponseExample:
+            description: 'Example of a generic error response'
+            value:
+              statusCode: 400
+              error: 'Bad Request'
+              message: 'An error message describing what went wrong'

x-pack/platform/plugins/shared/fleet/server/types/models/custom_integrations.ts

@@ -15,6 +15,6 @@ const CustomIntegrationFieldsSchema = schema.object({
 export const CustomIntegrationRequestSchema = {
   body: CustomIntegrationFieldsSchema,
   params: schema.object({
-    pkgName: schema.string(),
+    pkgName: schema.string({ meta: { description: 'Package name' } }),
   }),
 };

x-pack/platform/plugins/shared/fleet/server/types/rest_spec/agent.ts

@@ -34,10 +34,14 @@ const ActionIdOrMessageSchema = schema.oneOf([
 export const GetAgentsRequestSchema = {
   query: schema.object(
     {
-      page: schema.maybe(schema.number()),
-      perPage: schema.number({ defaultValue: 20 }),
+      page: schema.maybe(schema.number({ meta: { description: 'Page number' } })),
+      perPage: schema.number({
+        defaultValue: 20,
+        meta: { description: 'Number of results per page' },
+      }),
       kuery: schema.maybe(
         schema.string({
+          meta: { description: 'A KQL query string to filter results' },
           validate: (value: string) => {
             const validationObj = validateKuery(value, [AGENTS_PREFIX], AGENT_MAPPINGS, true);
             if (validationObj?.error) {
@@ -46,17 +50,50 @@ export const GetAgentsRequestSchema = {
           },
         })
       ),
-      showAgentless: schema.boolean({ defaultValue: true }),
-      showInactive: schema.boolean({ defaultValue: false }),
-      withMetrics: schema.boolean({ defaultValue: false }),
-      showUpgradeable: schema.boolean({ defaultValue: false }),
-      getStatusSummary: schema.boolean({ defaultValue: false }),
-      sortField: schema.maybe(schema.string()),
-      sortOrder: schema.maybe(schema.oneOf([schema.literal('asc'), schema.literal('desc')])),
-      searchAfter: schema.maybe(schema.string()),
-      openPit: schema.maybe(schema.boolean()),
-      pitId: schema.maybe(schema.string()),
-      pitKeepAlive: schema.maybe(schema.string()),
+      showAgentless: schema.boolean({
+        defaultValue: true,
+        meta: { description: 'When true, include agentless agents in the results' },
+      }),
+      showInactive: schema.boolean({
+        defaultValue: false,
+        meta: { description: 'When true, include inactive agents in the results' },
+      }),
+      withMetrics: schema.boolean({
+        defaultValue: false,
+        meta: { description: 'When true, include CPU and memory metrics in the response' },
+      }),
+      showUpgradeable: schema.boolean({
+        defaultValue: false,
+        meta: { description: 'When true, only return agents that are upgradeable' },
+      }),
+      getStatusSummary: schema.boolean({
+        defaultValue: false,
+        meta: { description: 'When true, return a summary of agent statuses in the response' },
+      }),
+      sortField: schema.maybe(schema.string({ meta: { description: 'Field to sort results by' } })),
+      sortOrder: schema.maybe(
+        schema.oneOf([schema.literal('asc'), schema.literal('desc')], {
+          meta: { description: 'Sort order, ascending or descending' },
+        })
+      ),
+      searchAfter: schema.maybe(
+        schema.string({
+          meta: { description: 'JSON-encoded array of sort values for `search_after` pagination' },
+        })
+      ),
+      openPit: schema.maybe(
+        schema.boolean({
+          meta: { description: 'When true, opens a new point-in-time for pagination' },
+        })
+      ),
+      pitId: schema.maybe(
+        schema.string({ meta: { description: 'Point-in-time ID for pagination' } })
+      ),
+      pitKeepAlive: schema.maybe(
+        schema.string({
+          meta: { description: 'Duration to keep the point-in-time alive, for example, `1m`' },
+        })
+      ),
     },
     {
       validate: (request) => {
@@ -354,10 +391,13 @@ export const GetAgentResponseSchema = schema.object({
 
 export const GetOneAgentRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   query: schema.object({
-    withMetrics: schema.boolean({ defaultValue: false }),
+    withMetrics: schema.boolean({
+      defaultValue: false,
+      meta: { description: 'When true, include CPU and memory metrics in the response' },
+    }),
   }),
 };
 
@@ -378,7 +418,7 @@ export const PostNewAgentActionRequestSchema = {
     action: NewAgentActionSchema,
   }),
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
 };
 
@@ -403,7 +443,7 @@ export const PostNewAgentActionResponseSchema = schema.object({
 
 export const PostCancelActionRequestSchema = {
   params: schema.object({
-    actionId: schema.string(),
+    actionId: schema.string({ meta: { description: 'The ID of the action to cancel' } }),
   }),
 };
 
@@ -419,7 +459,7 @@ export const PostRetrieveAgentsByActionsResponseSchema = schema.object({
 
 export const PostAgentUnenrollRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   body: schema.nullable(
     schema.object({
@@ -479,7 +519,7 @@ function validateVersion(s: string) {
 
 export const PostAgentUpgradeRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   body: schema.object({
     source_uri: schema.maybe(schema.string()),
@@ -515,7 +555,7 @@ export const PostBulkAgentUpgradeRequestSchema = {
 
 export const PostAgentReassignRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   body: schema.object({
     policy_id: schema.string(),
@@ -524,7 +564,7 @@ export const PostAgentReassignRequestSchema = {
 
 export const PostRequestDiagnosticsActionRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   body: schema.nullable(
     schema.object({
@@ -551,7 +591,7 @@ export const PostBulkRequestDiagnosticsActionRequestSchema = {
 
 export const ListAgentUploadsRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
 };
 
@@ -579,14 +619,14 @@ export const ListAgentUploadsResponseSchema = schema.object({
 
 export const GetAgentUploadFileRequestSchema = {
   params: schema.object({
-    fileId: schema.string(),
-    fileName: schema.string(),
+    fileId: schema.string({ meta: { description: 'The ID of the uploaded file' } }),
+    fileName: schema.string({ meta: { description: 'The name of the uploaded file' } }),
   }),
 };
 
 export const DeleteAgentUploadFileRequestSchema = {
   params: schema.object({
-    fileId: schema.string(),
+    fileId: schema.string({ meta: { description: 'The ID of the uploaded file' } }),
   }),
 };
 
@@ -606,7 +646,7 @@ export const PostBulkAgentReassignRequestSchema = {
 
 export const DeleteAgentRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
 };
 
@@ -616,7 +656,7 @@ export const DeleteAgentResponseSchema = schema.object({
 
 export const UpdateAgentRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   body: schema.object({
     user_provided_metadata: schema.maybe(schema.recordOf(schema.string(), schema.any())),
@@ -626,7 +666,7 @@ export const UpdateAgentRequestSchema = {
 
 export const MigrateSingleAgentRequestSchema = {
   params: schema.object({
-    agentId: schema.string(),
+    agentId: schema.string({ meta: { description: 'The agent ID' } }),
   }),
   body: schema.object({
     uri: schema.uri(),
@@ -663,12 +703,15 @@ export const PostBulkActionResponseSchema = ActionIdSchema;
 
 export const GetAgentStatusRequestSchema = {
   query: schema.object({
-    policyId: schema.maybe(schema.string()),
+    policyId: schema.maybe(schema.string({ meta: { description: 'Filter by agent policy ID' } })),
     policyIds: schema.maybe(
-      schema.oneOf([schema.arrayOf(schema.string(), { maxSize: 1000 }), schema.string()])
+      schema.oneOf([schema.arrayOf(schema.string(), { maxSize: 1000 }), schema.string()], {
+        meta: { description: 'Filter by one or more agent policy IDs' },
+      })
     ),
     kuery: schema.maybe(
       schema.string({
+        meta: { description: 'A KQL query string to filter results' },
         validate: (value: string) => {
           const validationObj = validateKuery(value, [AGENTS_PREFIX], AGENT_MAPPINGS, true);
           if (validationObj?.error) {
@@ -699,10 +742,22 @@ export const GetAgentStatusResponseSchema = schema.object({
 
 export const GetAgentDataRequestSchema = {
   query: schema.object({
-    agentsIds: schema.oneOf([schema.arrayOf(schema.string(), { maxSize: 10000 }), schema.string()]),
-    pkgName: schema.maybe(schema.string()),
-    pkgVersion: schema.maybe(schema.string()),
-    previewData: schema.boolean({ defaultValue: false }),
+    agentsIds: schema.oneOf(
+      [schema.arrayOf(schema.string(), { maxSize: 10000 }), schema.string()],
+      {
+        meta: { description: 'Agent IDs to check data for, as an array or comma-separated string' },
+      }
+    ),
+    pkgName: schema.maybe(
+      schema.string({ meta: { description: 'Filter by integration package name' } })
+    ),
+    pkgVersion: schema.maybe(
+      schema.string({ meta: { description: 'Filter by integration package version' } })
+    ),
+    previewData: schema.boolean({
+      defaultValue: false,
+      meta: { description: 'When true, return a preview of the ingested data' },
+    }),
   }),
 };
 
@@ -721,19 +776,28 @@ export const GetAgentDataResponseSchema = schema.object({
 
 export const GetActionStatusRequestSchema = {
   query: schema.object({
-    page: schema.number({ defaultValue: 0 }),
-    perPage: schema.number({ defaultValue: 20 }),
+    page: schema.number({ defaultValue: 0, meta: { description: 'Page number' } }),
+    perPage: schema.number({
+      defaultValue: 20,
+      meta: { description: 'Number of results per page' },
+    }),
     date: schema.maybe(
       schema.string({
+        meta: { description: 'Return actions created before this date' },
         validate: (v: string) => {
           if (!moment(v).isValid()) {
             return 'not a valid date';
           }
         },
       })
     ),
-    latest: schema.maybe(schema.number()),
-    errorSize: schema.number({ defaultValue: 5 }),
+    latest: schema.maybe(
+      schema.number({ meta: { description: 'Return only the latest N actions' } })
+    ),
+    errorSize: schema.number({
+      defaultValue: 5,
+      meta: { description: 'Number of error details to include per action' },
+    }),
   }),
 };