[OpenAPI][Fleet] Add operation summaries

elastic · Nov 8, 2024 · f07a288 · f07a288
1 parent fcc3b06
commit f07a288
Show file tree

Hide file tree

Showing 16 changed files with 140 additions and 107 deletions.
diff --git a/x-pack/plugins/fleet/server/routes/agent/index.ts b/x-pack/plugins/fleet/server/routes/agent/index.ts
@@ -97,7 +97,8 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Get agent by ID`,
+      summary: `Get an agent`,
+      description: `Get an agent by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -127,7 +128,8 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Update agent by ID`,
+      summary: `Update an agent`,
+      description: `Update an agent by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -157,7 +159,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Bulk update agent tags`,
+      summary: `Bulk update agent tags`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -187,7 +189,8 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Delete agent by ID`,
+      summary: `Delete an agent`,
+      description: `Delete an agent by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -218,7 +221,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `List agents`,
+      summary: `Get agents`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -248,7 +251,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `List agent tags`,
+      summary: `Get agent tags`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -278,7 +281,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Create agent action`,
+      summary: `Create an agent action`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -312,7 +315,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Cancel agent action`,
+      summary: `Cancel an agent action`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -347,7 +350,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `List agents by action ids`,
+      summary: `Get agents by action ids`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -376,7 +379,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Unenroll agent`,
+      summary: `Unenroll an agent`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -395,7 +398,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Reassign agent`,
+      summary: `Reassign an agent`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -424,7 +427,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Request agent diagnostics`,
+      summary: `Request agent diagnostics`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -453,7 +456,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Bulk request diagnostics from agents`,
+      summary: `Bulk request diagnostics from agents`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -482,7 +485,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `List agent uploads`,
+      summary: `Get agent uploads`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -511,7 +514,8 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Get file uploaded by agent`,
+      summary: `Get an uploaded file`,
+      description: `Get a file uploaded by an agent.`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -540,7 +544,8 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Delete file uploaded by agent`,
+      summary: `Delete an uploaded file`,
+      description: `Delete a file uploaded by an agent.`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -572,7 +577,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
           fleetAuthz,
           getRouteRequiredAuthz('get', AGENT_API_ROUTES.STATUS_PATTERN)
         ).granted,
-      description: `Get agent status summary`,
+      summary: `Get an agent status summary`,
       options: {
         tags: ['oas-tag:Elastic Agent status'],
       },
@@ -601,7 +606,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Get incoming agent data`,
+      summary: `Get incoming agent data`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },
@@ -631,7 +636,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Upgrade agent`,
+      summary: `Upgrade an agent`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -660,7 +665,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Bulk upgrade agents`,
+      summary: `Bulk upgrade agents`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -690,7 +695,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Get agent action status`,
+      summary: `Get an agent action status`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -720,7 +725,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Bulk reassign agents`,
+      summary: `Bulk reassign agents`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -750,7 +755,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Bulk unenroll agents`,
+      summary: `Bulk unenroll agents`,
       options: {
         tags: ['oas-tag:Elastic Agent actions'],
       },
@@ -780,7 +785,7 @@ export const registerAPIRoutes = (router: FleetAuthzRouter, config: FleetConfigT
       fleetAuthz: {
         fleet: { readAgents: true },
       },
-      description: `Get available agent versions`,
+      summary: `Get available agent versions`,
       options: {
         tags: ['oas-tag:Elastic Agents'],
       },

diff --git a/x-pack/plugins/fleet/server/routes/agent_policy/index.ts b/x-pack/plugins/fleet/server/routes/agent_policy/index.ts
@@ -64,7 +64,7 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
         //  Allow to retrieve agent policies metadata (no full) for user with only read agents permissions
         return authz.fleet.readAgentPolicies || authz.fleet.readAgents;
       },
-      description: `List agent policies`,
+      summary: `Get agent policies`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -95,7 +95,7 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
         //  Allow to retrieve agent policies metadata (no full) for user with only read agents permissions
         return authz.fleet.readAgentPolicies || authz.fleet.readAgents;
       },
-      description: `Bulk get agent policies`,
+      summary: `Bulk get agent policies`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -126,7 +126,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
         //  Allow to retrieve agent policies metadata (no full) for user with only read agents permissions
         return authz.fleet.readAgentPolicies || authz.fleet.readAgents;
       },
-      description: `Get an agent policy by ID`,
+      summary: `Get an agent policy`,
+      description: `Get an agent policy by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -156,7 +157,7 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { allAgentPolicies: true },
       },
-      description: `Create an agent policy`,
+      summary: `Create an agent policy`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -186,7 +187,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { allAgentPolicies: true },
       },
-      description: `Update an agent policy by ID`,
+      summary: `Update an agent policy`,
+      description: `Update an agent policy by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -216,7 +218,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { allAgentPolicies: true },
       },
-      description: `Copy an agent policy by ID`,
+      summary: `Copy an agent policy`,
+      description: `Copy an agent policy by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -246,7 +249,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { allAgentPolicies: true },
       },
-      description: `Delete agent policy by ID`,
+      summary: `Delete an agent policy`,
+      description: `Delete an agent policy by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -276,7 +280,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { readAgentPolicies: true },
       },
-      description: `Get a full agent policy by ID`,
+      summary: `Get a full agent policy`,
+      description: `Get a full agent policy by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -307,7 +312,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
         fleet: { readAgentPolicies: true },
       },
       enableQueryVersion: true,
-      description: `Download an agent policy by ID`,
+      summary: `Download an agent policy`,
+      description: `Download an agent policy by ID.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -340,7 +346,7 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { readAgentPolicies: true },
       },
-      description: `Get full K8s agent manifest`,
+      summary: `Get a full K8s agent manifest`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -371,7 +377,7 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
         fleet: { readAgentPolicies: true },
       },
       enableQueryVersion: true,
-      description: ``,
+      summary: `Download an agent manifest`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -403,7 +409,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: (authz) => {
         return authz.fleet.readAgentPolicies && authz.fleet.readSettings;
       },
-      description: `Get list of outputs associated with agent policies`,
+      summary: `Get outputs for agent policies`,
+      description: `Get a list of outputs associated with agent policies.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },
@@ -432,7 +439,8 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: (authz) => {
         return authz.fleet.readAgentPolicies && authz.fleet.readSettings;
       },
-      description: `Get list of outputs associated with agent policy by policy id`,
+      summary: `Get outputs for an agent policy`,
+      description: `Get a list of outputs associated with agent policy by policy id.`,
       options: {
         tags: ['oas-tag:Elastic Agent policies'],
       },

diff --git a/x-pack/plugins/fleet/server/routes/app/index.ts b/x-pack/plugins/fleet/server/routes/app/index.ts
@@ -218,7 +218,7 @@ export const registerRoutes = (router: FleetAuthzRouter, config: FleetConfigType
   router.versioned
     .get({
       path: APP_API_ROUTES.CHECK_PERMISSIONS_PATTERN,
-      description: `Check permissions`,
+      summary: `Check permissions`,
       options: {
         tags: ['oas-tag:Fleet internals'],
       },
@@ -263,7 +263,7 @@ export const registerRoutes = (router: FleetAuthzRouter, config: FleetConfigType
       fleetAuthz: {
         fleet: { allAgents: true },
       },
-      description: `Create a service token`,
+      summary: `Create a service token`,
       options: {
         tags: ['oas-tag:Fleet service tokens'],
       },

diff --git a/x-pack/plugins/fleet/server/routes/data_streams/index.ts b/x-pack/plugins/fleet/server/routes/data_streams/index.ts
@@ -52,7 +52,7 @@ export const registerRoutes = (router: FleetAuthzRouter) => {
       fleetAuthz: {
         fleet: { all: true },
       },
-      description: `List data streams`,
+      summary: `Get data streams`,
       options: {
         tags: ['oas-tag:Data streams'],
       },