[HTTP/OAS] Prepare @kbn/config-schema for generating OAS (#180184)

## Summary Introduces a set of meta fields that will be used to track metadata lost in how we currently use `joi` inside of `@kbn/config-schema`. ## Notes * Related #180056 * Changes cherry-picked from #156357 * Changes are not used for anything in this PR, they are intended to enable our OAS generation scripts
elastic · Apr 9, 2024 · 5336a23 · 5336a23
1 parent 66fcd17
commit 5336a23
Show file tree

Hide file tree

Showing 14 changed files with 1,401 additions and 16 deletions.
diff --git a/packages/kbn-config-schema/index.ts b/packages/kbn-config-schema/index.ts
@@ -238,3 +238,17 @@ export const schema = {
 };
 
 export type Schema = typeof schema;
+
+import {
+  META_FIELD_X_OAS_OPTIONAL,
+  META_FIELD_X_OAS_MAX_LENGTH,
+  META_FIELD_X_OAS_MIN_LENGTH,
+  META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES,
+} from './src/oas_meta_fields';
+
+export const metaFields = Object.freeze({
+  META_FIELD_X_OAS_OPTIONAL,
+  META_FIELD_X_OAS_MAX_LENGTH,
+  META_FIELD_X_OAS_MIN_LENGTH,
+  META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES,
+});
diff --git a/packages/kbn-config-schema/src/oas_meta_fields.ts b/packages/kbn-config-schema/src/oas_meta_fields.ts
@@ -0,0 +1,17 @@
+/*
+ * 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.
+ */
+
+/**
+ * These fields are used in Joi meta to capture additional information used
+ * by OpenAPI spec generator.
+ */
+export const META_FIELD_X_OAS_OPTIONAL = 'x-oas-optional' as const;
+export const META_FIELD_X_OAS_MIN_LENGTH = 'x-oas-min-length' as const;
+export const META_FIELD_X_OAS_MAX_LENGTH = 'x-oas-max-length' as const;
+export const META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES =
+  'x-oas-get-additional-properties' as const;
diff --git a/...nfig-schema/src/types/map_of_type.test.ts → ...-config-schema/src/types/map_type.test.ts b/...nfig-schema/src/types/map_of_type.test.ts → ...-config-schema/src/types/map_type.test.ts
@@ -7,6 +7,7 @@
  */
 
 import { schema } from '../..';
+import { META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES } from '../oas_meta_fields';
 
 test('handles object as input', () => {
   const type = schema.mapOf(schema.string(), schema.string());
@@ -186,6 +187,17 @@ test('error preserves full path', () => {
   );
 });
 
+test('meta', () => {
+  const stringSchema = schema.string();
+  const type = schema.mapOf(schema.string(), stringSchema);
+  const result = type
+    .getSchema()
+    .describe()
+    .metas![0][META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES]();
+
+  expect(result).toBe(stringSchema.getSchema());
+});
+
 describe('#extendsDeep', () => {
   describe('#keyType', () => {
     const type = schema.mapOf(schema.string(), schema.object({ foo: schema.string() }));

diff --git a/packages/kbn-config-schema/src/types/map_type.ts b/packages/kbn-config-schema/src/types/map_type.ts
@@ -9,6 +9,7 @@
 import typeDetect from 'type-detect';
 import { SchemaTypeError, SchemaTypesError } from '../errors';
 import { internals } from '../internals';
+import { META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES } from '../oas_meta_fields';
 import { Type, TypeOptions, ExtendsDeepOptions } from './type';
 
 export type MapOfOptions<K, V> = TypeOptions<Map<K, V>>;
@@ -20,7 +21,12 @@ export class MapOfType<K, V> extends Type<Map<K, V>> {
 
   constructor(keyType: Type<K>, valueType: Type<V>, options: MapOfOptions<K, V> = {}) {
     const defaultValue = options.defaultValue;
-    const schema = internals.map().entries(keyType.getSchema(), valueType.getSchema());
+    const schema = internals
+      .map()
+      .entries(keyType.getSchema(), valueType.getSchema())
+      .meta({
+        [META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES]: () => valueType.getSchema(),
+      });
 
     super(schema, {
       ...options,

diff --git a/packages/kbn-config-schema/src/types/maybe_type.test.ts b/packages/kbn-config-schema/src/types/maybe_type.test.ts
@@ -7,6 +7,7 @@
  */
 
 import { schema } from '../..';
+import { META_FIELD_X_OAS_OPTIONAL } from '../oas_meta_fields';
 
 test('returns value if specified', () => {
   const type = schema.maybe(schema.string());
@@ -96,6 +97,12 @@ describe('maybe + object', () => {
   });
 });
 
+test('meta', () => {
+  const maybeString = schema.maybe(schema.string());
+  const result = maybeString.getSchema().describe().metas[0];
+  expect(result).toEqual({ [META_FIELD_X_OAS_OPTIONAL]: true });
+});
+
 describe('#extendsDeep', () => {
   const type = schema.maybe(schema.object({ foo: schema.string() }));
 

diff --git a/packages/kbn-config-schema/src/types/maybe_type.ts b/packages/kbn-config-schema/src/types/maybe_type.ts
@@ -8,6 +8,7 @@
 
 import { Type, ExtendsDeepOptions } from './type';
 
+import { META_FIELD_X_OAS_OPTIONAL } from '../oas_meta_fields';
 export class MaybeType<V> extends Type<V | undefined> {
   private readonly maybeType: Type<V>;
 
@@ -16,6 +17,7 @@ export class MaybeType<V> extends Type<V | undefined> {
       type
         .getSchema()
         .optional()
+        .meta({ [META_FIELD_X_OAS_OPTIONAL]: true })
         .default(() => undefined)
     );
     this.maybeType = type;

diff --git a/packages/kbn-config-schema/src/types/record_type.test.ts b/packages/kbn-config-schema/src/types/record_type.test.ts
@@ -7,6 +7,7 @@
  */
 
 import { schema } from '../..';
+import { META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES } from '../oas_meta_fields';
 
 test('handles object as input', () => {
   const type = schema.recordOf(schema.string(), schema.string());
@@ -208,3 +209,14 @@ describe('#extendsDeep', () => {
     ).toThrowErrorMatchingInlineSnapshot(`"[key.bar]: definition for this key is missing"`);
   });
 });
+
+test('meta', () => {
+  const stringSchema = schema.string();
+  const type = schema.mapOf(schema.string(), stringSchema);
+  const result = type
+    .getSchema()
+    .describe()
+    .metas![0][META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES]();
+
+  expect(result).toBe(stringSchema.getSchema());
+});
diff --git a/packages/kbn-config-schema/src/types/record_type.ts b/packages/kbn-config-schema/src/types/record_type.ts
@@ -10,6 +10,7 @@ import typeDetect from 'type-detect';
 import { SchemaTypeError, SchemaTypesError } from '../errors';
 import { internals } from '../internals';
 import { Type, TypeOptions, ExtendsDeepOptions } from './type';
+import { META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES } from '../oas_meta_fields';
 
 export type RecordOfOptions<K extends string, V> = TypeOptions<Record<K, V>>;
 
@@ -19,7 +20,12 @@ export class RecordOfType<K extends string, V> extends Type<Record<K, V>> {
   private readonly options: RecordOfOptions<K, V>;
 
   constructor(keyType: Type<K>, valueType: Type<V>, options: RecordOfOptions<K, V> = {}) {
-    const schema = internals.record().entries(keyType.getSchema(), valueType.getSchema());
+    const schema = internals
+      .record()
+      .entries(keyType.getSchema(), valueType.getSchema())
+      .meta({
+        [META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES]: () => valueType.getSchema(),
+      });
 
     super(schema, options);
     this.keyType = keyType;

diff --git a/packages/kbn-config-schema/src/types/string_type.test.ts b/packages/kbn-config-schema/src/types/string_type.test.ts
@@ -7,6 +7,7 @@
  */
 
 import { schema } from '../..';
+import { META_FIELD_X_OAS_MAX_LENGTH, META_FIELD_X_OAS_MIN_LENGTH } from '../oas_meta_fields';
 
 test('returns value is string and defined', () => {
   expect(schema.string().validate('test')).toBe('test');
@@ -166,6 +167,17 @@ describe('#defaultValue', () => {
   });
 });
 
+test('meta', () => {
+  const string = schema.string({ minLength: 1, maxLength: 3 });
+  const [meta1, meta2] = string.getSchema().describe().metas;
+  expect(meta1).toEqual({
+    [META_FIELD_X_OAS_MIN_LENGTH]: 1,
+  });
+  expect(meta2).toEqual({
+    [META_FIELD_X_OAS_MAX_LENGTH]: 3,
+  });
+});
+
 describe('#validate', () => {
   test('is called with input value', () => {
     let calledWith;

diff --git a/packages/kbn-config-schema/src/types/string_type.ts b/packages/kbn-config-schema/src/types/string_type.ts
@@ -10,6 +10,8 @@ import typeDetect from 'type-detect';
 import { internals } from '../internals';
 import { Type, TypeOptions, convertValidationFunction } from './type';
 
+import { META_FIELD_X_OAS_MIN_LENGTH, META_FIELD_X_OAS_MAX_LENGTH } from '../oas_meta_fields';
+
 export type StringOptions = TypeOptions<string> & {
   minLength?: number;
   maxLength?: number;
@@ -37,24 +39,29 @@ export class StringType extends Type<string> {
             }
             return value;
           });
+
     if (options.minLength !== undefined) {
-      schema = schema.custom(
-        convertValidationFunction((value) => {
-          if (value.length < options.minLength!) {
-            return `value has length [${value.length}] but it must have a minimum length of [${options.minLength}].`;
-          }
-        })
-      );
+      schema = schema
+        .custom(
+          convertValidationFunction((value) => {
+            if (value.length < options.minLength!) {
+              return `value has length [${value.length}] but it must have a minimum length of [${options.minLength}].`;
+            }
+          })
+        )
+        .meta({ [META_FIELD_X_OAS_MIN_LENGTH]: options.minLength });
     }
 
     if (options.maxLength !== undefined) {
-      schema = schema.custom(
-        convertValidationFunction((value) => {
-          if (value.length > options.maxLength!) {
-            return `value has length [${value.length}] but it must have a maximum length of [${options.maxLength}].`;
-          }
-        })
-      );
+      schema = schema
+        .custom(
+          convertValidationFunction((value) => {
+            if (value.length > options.maxLength!) {
+              return `value has length [${value.length}] but it must have a maximum length of [${options.maxLength}].`;
+            }
+          })
+        )
+        .meta({ [META_FIELD_X_OAS_MAX_LENGTH]: options.maxLength });
     }
 
     schema.type = 'string';

diff --git a/packages/kbn-config-schema/src/types/type.test.ts b/packages/kbn-config-schema/src/types/type.test.ts
@@ -0,0 +1,23 @@
+/*
+ * 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 { get } from 'lodash';
+import { internals } from '../internals';
+import { Type, TypeOptions } from './type';
+
+class MyType extends Type<any> {
+  constructor(opts: TypeOptions<any> = {}) {
+    super(internals.any(), opts);
+  }
+}
+
+test('describe', () => {
+  const type = new MyType({ description: 'my description' });
+  const meta = type.getSchema().describe();
+  expect(get(meta, 'flags.description')).toBe('my description');
+});
diff --git a/packages/kbn-config-schema/src/types/type.ts b/packages/kbn-config-schema/src/types/type.ts
@@ -13,6 +13,8 @@ import { Reference } from '../references';
 export interface TypeOptions<T> {
   defaultValue?: T | Reference<T> | (() => T);
   validate?: (value: T) => string | void;
+  /** A human-friendly description of this type to be used in documentation */
+  description?: string;
 }
 
 export interface SchemaStructureEntry {
@@ -86,6 +88,10 @@ export abstract class Type<V> {
       schema = schema.custom(convertValidationFunction(options.validate));
     }
 
+    if (options.description) {
+      schema = schema.description(options.description);
+    }
+
     // Attach generic error handler only if it hasn't been attached yet since
     // only the last error handler is counted.
     if (schema.$_getFlag('error') === undefined) {