[HTTP/OAS] Added response schemas for /api/status

packages/core/status/core-status-server-internal/src/routes/status.ts

@@ -13,14 +13,14 @@ import type { PluginName } from '@kbn/core-base-common';
 import type { IRouter } from '@kbn/core-http-server';
 import type { MetricsServiceSetup } from '@kbn/core-metrics-server';
 import type { CoreIncrementUsageCounter } from '@kbn/core-usage-data-server';
-import type { StatusResponse } from '@kbn/core-status-common-internal';
-import {
-  type ServiceStatus,
-  type ServiceStatusLevel,
-  type CoreStatus,
-  ServiceStatusLevels,
-} from '@kbn/core-status-common';
+import { type ServiceStatus, type CoreStatus, ServiceStatusLevels } from '@kbn/core-status-common';
+import { StatusResponse } from '@kbn/core-status-common-internal';
 import { calculateLegacyStatus, type LegacyStatusInfo } from '../legacy_status';
+import {
+  statusResponse,
+  redactedStatusResponse,
+  type RedactedStatusHttpBody,
+} from './status_response_schemas';
 
 const SNAPSHOT_POSTFIX = /-SNAPSHOT$/;
 
@@ -53,19 +53,17 @@ interface StatusHttpBody extends Omit<StatusResponse, 'status'> {
   status: StatusInfo | LegacyStatusInfo;
 }
 
-export interface RedactedStatusHttpBody {
-  status: {
-    overall: {
-      level: ServiceStatusLevel;
-    };
-  };
-}
-
 const SERVICE_UNAVAILABLE_NOT_REPORTED: ServiceStatus = {
   level: ServiceStatusLevels.unavailable,
   summary: 'Status not yet reported',
 };
 
+const responseSchema = schema.oneOf([redactedStatusResponse, statusResponse], {
+  meta: {
+    description: `Kibana's operational status. A minimal response is sent for unauthorized users.`,
+  },
+});
+
 export const registerStatusRoute = ({
   router,
   config,
@@ -100,21 +98,32 @@ export const registerStatusRoute = ({
         // ROUTE_TAG_ACCEPT_JWT from '@kbn/security-plugin/server' that cannot be imported here directly.
         tags: ['api', 'security:acceptJWT'],
         access: 'public', // needs to be public to allow access from "system" users like k8s readiness probes.
+        description: `Get Kibana's current status.`,
       },
       validate: {
-        query: schema.object(
-          {
-            v7format: schema.maybe(schema.boolean()),
-            v8format: schema.maybe(schema.boolean()),
-          },
-          {
-            validate: ({ v7format, v8format }) => {
-              if (typeof v7format === 'boolean' && typeof v8format === 'boolean') {
-                return `provide only one format option: v7format or v8format`;
-              }
+        request: {
+          query: schema.object(
+            {
+              v7format: schema.maybe(schema.boolean()),
+              v8format: schema.maybe(schema.boolean()),
             },
-          }
-        ),
+            {
+              validate: ({ v7format, v8format }) => {
+                if (typeof v7format === 'boolean' && typeof v8format === 'boolean') {
+                  return `provide only one format option: v7format or v8format`;
+                }
+              },
+            }
+          ),
+        },
+        response: {
+          200: {
+            body: responseSchema,
+          },
+          503: {
+            body: responseSchema,
+          },
+        },
       },
     },
     async (context, req, res) => {
@@ -217,7 +226,7 @@ const getRedactedStatusResponse = ({
   const body: RedactedStatusHttpBody = {
     status: {
       overall: {
-        level: coreOverall.level,
+        level: coreOverall.level.toString(),
       },
     },
   };

packages/core/status/core-status-server-internal/src/routes/status_preboot.ts

@@ -8,7 +8,7 @@
 
 import type { IRouter } from '@kbn/core-http-server';
 import { ServiceStatusLevels } from '@kbn/core-status-common';
-import type { RedactedStatusHttpBody } from './status';
+import type { RedactedStatusHttpBody } from './status_response_schemas';
 
 export const registerPrebootStatusRoute = ({ router }: { router: IRouter }) => {
   router.get(
@@ -25,7 +25,7 @@ export const registerPrebootStatusRoute = ({ router }: { router: IRouter }) => {
       const body: RedactedStatusHttpBody = {
         status: {
           overall: {
-            level: ServiceStatusLevels.unavailable,
+            level: ServiceStatusLevels.unavailable.toString(),
           },
         },
       };

packages/core/status/core-status-server-internal/src/routes/status_response_schemas.ts

@@ -0,0 +1,105 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { schema, type Type, type TypeOf } from '@kbn/config-schema';
+import type { BuildFlavor } from '@kbn/config';
+import type { ServiceStatusLevelId, ServiceStatus } from '@kbn/core-status-common';
+
+import type {
+  StatusResponse,
+  StatusInfoCoreStatus,
+  ServerMetrics,
+  StatusInfo,
+  ServerVersion,
+} from '@kbn/core-status-common-internal';
+
+export const serviceStatusLevelId: Type<ServiceStatusLevelId> = schema.oneOf([
+  schema.literal('available'),
+  schema.literal('degraded'),
+  schema.literal('unavailable'),
+  schema.literal('critical'),
+]);
+
+export const statusInfoServiceStatus: Type<
+  Omit<ServiceStatus, 'level'> & { level: ServiceStatusLevelId }
+> = schema.object({
+  level: serviceStatusLevelId,
+  summary: schema.string(),
+  detail: schema.maybe(schema.string()),
+  documentationUrl: schema.maybe(schema.string()),
+  meta: schema.recordOf(schema.string(), schema.any()),
+});
+
+export const statusInfoCoreStatus: Type<StatusInfoCoreStatus> = schema.object({
+  elasticsearch: statusInfoServiceStatus,
+  savedObjects: statusInfoServiceStatus,
+});
+
+/** Only include a subset of fields for OAS documentation, for now */
+export const serverMetrics: Type<Partial<ServerMetrics>> = schema.object({
+  elasticsearch_client: schema.object({
+    totalActiveSockets: schema.number(),
+    totalIdleSockets: schema.number(),
+    totalQueuedRequests: schema.number(),
+  }),
+  last_updated: schema.string(),
+  collection_interval_in_millis: schema.number(),
+});
+
+export const buildFlavour: Type<BuildFlavor> = schema.oneOf([
+  schema.literal('serverless'),
+  schema.literal('traditional'),
+]);
+export const serverVersion: Type<ServerVersion> = schema.object({
+  number: schema.string(),
+  build_hash: schema.string(),
+  build_number: schema.number(),
+  build_snapshot: schema.boolean(),
+  build_flavor: buildFlavour,
+  build_date: schema.string(),
+});
+
+export const statusInfo: Type<StatusInfo> = schema.object({
+  overall: statusInfoServiceStatus,
+  core: statusInfoCoreStatus,
+  plugins: schema.recordOf(schema.string(), statusInfoServiceStatus),
+});
+
+/** Excluding metrics for brevity, for now */
+export const statusResponse: Type<Omit<StatusResponse, 'metrics'>> = schema.object(
+  {
+    name: schema.string(),
+    uuid: schema.string(),
+    version: serverVersion,
+    status: statusInfo,
+    metrics: serverMetrics,
+  },
+  {
+    meta: {
+      id: 'core.status.response',
+      description: `Kibana's operational status as well as a detailed breakdown of plugin statuses indication of various loads (like event loop utilization and network traffic) at time of request.`,
+    },
+  }
+);
+
+export const redactedStatusResponse = schema.object(
+  {
+    status: schema.object({
+      overall: schema.object({
+        level: serviceStatusLevelId,
+      }),
+    }),
+  },
+  {
+    meta: {
+      id: 'core.status.redactedResponse',
+    },
+  }
+);
+
+export type RedactedStatusHttpBody = TypeOf<typeof redactedStatusResponse>;

packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts

@@ -52,10 +52,18 @@ const getRouterDefaults = () => ({
   isVersioned: false,
   path: '/foo/{id}',
   method: 'get',
+  options: {
+    tags: ['foo'],
+    description: 'route',
+  },
   validationSchemas: {
     request: {
-      params: schema.object({ id: schema.string({ maxLength: 36 }) }),
-      query: schema.object({ page: schema.number({ max: 999, min: 1, defaultValue: 1 }) }),
+      params: schema.object({
+        id: schema.string({ maxLength: 36, meta: { description: 'id' } }),
+      }),
+      query: schema.object({
+        page: schema.number({ max: 999, min: 1, defaultValue: 1, meta: { description: 'page' } }),
+      }),
       body: testSchema,
     },
     response: {
@@ -64,24 +72,31 @@ const getRouterDefaults = () => ({
       },
     },
   },
-  options: { tags: ['foo'] },
   handler: jest.fn(),
 });
 
 const getVersionedRouterDefaults = () => ({
   method: 'get',
   path: '/bar',
   options: {
+    description: 'versioned route',
     access: 'public',
   },
   handlers: [
     {
       fn: jest.fn(),
       options: {
         validate: {
-          request: { body: schema.object({ foo: schema.string() }) },
+          request: {
+            body: schema.object({ foo: schema.string() }, { meta: { description: 'foo' } }),
+          },
           response: {
-            [200]: { body: schema.object({ fooResponse: schema.string() }) },
+            [200]: {
+              body: schema.object(
+                { fooResponse: schema.string() },
+                { meta: { description: 'fooResponse' } }
+              ),
+            },
           },
         },
         version: 'oas-test-version-1',

packages/kbn-router-to-openapispec/src/generate_oas.ts

@@ -118,7 +118,7 @@ const extractVersionedResponses = (
       const schema = converter.convert(maybeSchema);
       acc[statusCode] = {
         ...acc[statusCode],
-        description: route.options.description ?? 'No description',
+        description: '',
         content: {
           ...((acc[statusCode] ?? {}) as OpenAPIV3.ResponseObject).content,
           [getVersionedContentString(handler.options.version)]: {
@@ -184,6 +184,7 @@ const processVersionedRouter = (
         handler && extractValidationSchemaFromVersionedHandler(handler)?.request?.body
       );
       const path: OpenAPIV3.PathItemObject = {
+        description: route.options.description ?? '',
         [route.method]: {
           requestBody: hasBody
             ? {
@@ -219,7 +220,6 @@ const extractResponses = (route: InternalRouterRoute, converter: OasConverter) =
           const oasSchema = converter.convert(schema.body);
           acc[statusCode] = {
             ...acc[statusCode],
-            description: route.options.description ?? 'No description',
             content: {
               ...((acc[statusCode] ?? {}) as OpenAPIV3.ResponseObject).content,
               [getVersionedContentString(LATEST_SERVERLESS_VERSION)]: {
@@ -271,6 +271,7 @@ const processRouter = (
       }
 
       const path: OpenAPIV3.PathItemObject = {
+        description: route.options.description ?? '',
         [route.method]: {
           requestBody: !!validationSchemas?.body
             ? {