@redocly/openapi-core 1.8.1 → 1.9.0

package/src/rules/common/__tests__/no-required-schema-properties-undefined.test.ts

@@ -0,0 +1,550 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('no-required-schema-properties-undefined', () => {
+  it('should report if one or more of the required properties are undefined', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Pet:
+                type: object
+                required:
+                  - name
+                  - id
+                  - test
+                properties:
+                  id:
+                    type: integer
+                    format: int64
+                  name:
+                    type: string
+                    example: doggie
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Pet/required/2",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'test' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report if one or more of the required properties are undefined, including allOf nested schemas', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Pet:
+                type: object
+                allOf:
+                  - properties:
+                      foo:
+                        type: string
+                required:
+                  - id
+                  - foo
+                  - test
+                properties:
+                  id:
+                    type: integer
+                    format: int64
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Pet/required/2",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'test' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report if one or more of the required properties are undefined when used in schema with allOf keyword', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Cat:
+                description: A representation of a cat
+                allOf:
+                  - $ref: '#/components/schemas/Pet'
+                  - type: object
+                    properties:
+                      huntingSkill:
+                        type: string
+                    required:
+                      - huntingSkill
+                      - name
+              Pet:
+                type: object
+                required:
+                  - photoUrls
+                properties:
+                  name:
+                    type: string
+                  photoUrls:
+                    type: string
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Cat/allOf/1/required/1",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'name' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report required properties are present after resolving $refs when used in schema with allOf keyword', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Cat:
+                description: A representation of a cat
+                allOf:
+                  - $ref: '#/components/schemas/Pet'
+                  - type: object
+                    properties:
+                      huntingSkill:
+                        type: string
+                    required:
+                      - huntingSkill
+                required:
+                  - name
+              Pet:
+                type: object
+                required:
+                  - photoUrls
+                properties:
+                  name:
+                    type: string
+                  photoUrls:
+                    type: string
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should report with few messages if more than one of the required properties are undefined', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Pet:
+                type: object
+                required:
+                  - name
+                  - id
+                  - test
+                  - test2
+                properties:
+                  id:
+                    type: integer
+                    format: int64
+                  name:
+                    type: string
+                    example: doggie
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Pet/required/2",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'test' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Pet/required/3",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'test2' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report if all of the required properties are present', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Pet:
+                type: object
+                required:
+                  - name
+                  - id
+                properties:
+                  id:
+                    type: integer
+                    format: int64
+                  name:
+                    type: string
+                    example: doggie
+                  test:
+                    type: string
+                    example: test
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should not cause stack overflow when there are circular references in schemas', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Cat:
+                description: A representation of a cat
+                allOf:
+                  - $ref: '#/components/schemas/Pet'
+                  - type: object
+                    properties:
+                      huntingSkill:
+                        type: string
+                    required:
+                      - huntingSkill
+                required:
+                  - name
+              Pet:
+                description: A schema of pet
+                allOf:
+                  - $ref: '#/components/schemas/Cat'
+                  - type: object
+                    required:
+                      - photoUrls
+                    properties:
+                      name:
+                        type: string
+                      photoUrls:
+                        type: string
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should report if there is any required schema that is undefined, including checking nested allOf schemas', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Cat:
+                description: A representation of a cat
+                allOf:
+                  - $ref: '#/components/schemas/Pet'
+                  - type: object
+                    properties:
+                      huntingSkill:
+                        type: string
+                    required:
+                      - huntingSkill
+                required:
+                  - test
+                  - id
+              Pet:
+                description: A schema of pet
+                allOf:
+                  - type: object
+                    required:
+                      - photoUrls
+                    properties:
+                      photoUrls:
+                        type: string
+                  - type: object
+                    required:
+                      - name
+                    properties:
+                      name:
+                        type: string
+                      id:
+                        type: string
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Cat/required/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'test' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report if required property is present in one of the nested reference schemas', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Animal:
+                type: object
+                properties:
+                  commonProperty:
+                    type: string
+              Mammal:
+                allOf:
+                  - $ref: '#/components/schemas/Animal'
+                  - type: object
+                    properties:
+                      furColor:
+                        type: string
+                    required:
+                      - furColor
+              Carnivore:
+                allOf:
+                  - $ref: '#/components/schemas/Mammal'
+                  - type: object
+                    properties:
+                      diet:
+                        type: string
+                    required:
+                      - diet
+              Tiger:
+                allOf:
+                  - $ref: '#/components/schemas/Carnivore'
+                  - type: object
+                    properties:
+                      stripes:
+                        type: boolean
+                    required:
+                      - stripes
+                required:
+                  - commonProperty
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should report if one or more of the required properties are undefined when used in schema with anyOf keyword', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Cat:
+                description: A representation of a cat
+                anyOf:
+                  - $ref: '#/components/schemas/Pet'
+                  - type: object
+                    properties:
+                      huntingSkill:
+                        type: string
+                    required:
+                      - huntingSkill
+                      - name
+              Pet:
+                type: object
+                required:
+                  - photoUrls
+                properties:
+                  name:
+                    type: string
+                  photoUrls:
+                    type: string
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/components/schemas/Cat/anyOf/1/required/1",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Required property 'name' is undefined.",
+          "ruleId": "no-required-schema-properties-undefined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report if one or more of the required properties are undefined when used in schema with allOf keyword', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components:
+            schemas:
+              Cat:
+                description: A representation of a cat
+                anyOf:
+                  - $ref: '#/components/schemas/Pet'
+                  - type: object
+                    properties:
+                      huntingSkill:
+                        type: string
+                    required:
+                      - huntingSkill
+                required:
+                  - name
+              Pet:
+                type: object
+                required:
+                  - photoUrls
+                properties:
+                  name:
+                    type: string
+                  photoUrls:
+                    type: string
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-required-schema-properties-undefined': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+});

package/src/rules/common/no-required-schema-properties-undefined.ts

@@ -0,0 +1,53 @@
+import { Oas2Rule, Oas3Rule } from '../../visitors';
+import { Oas3Schema, Oas3_1Schema } from '../../typings/openapi';
+import { Oas2Schema } from 'core/src/typings/swagger';
+import { UserContext } from 'core/src/walk';
+import { isRef } from '../../ref-utils';
+
+export const NoRequiredSchemaPropertiesUndefined: Oas3Rule | Oas2Rule = () => {
+  return {
+    Schema: {
+      enter(
+        schema: Oas3Schema | Oas3_1Schema | Oas2Schema,
+        { location, report, resolve }: UserContext
+      ) {
+        if (!schema.required) return;
+        const visitedSchemas: Set<Oas3Schema | Oas3_1Schema | Oas2Schema> = new Set();
+
+        const elevateProperties = (
+          schema: Oas3Schema | Oas3_1Schema | Oas2Schema
+        ): Record<string, Oas3Schema | Oas3_1Schema | Oas2Schema> => {
+          // Check if the schema has been visited before processing it
+          if (visitedSchemas.has(schema)) {
+            return {};
+          }
+          visitedSchemas.add(schema);
+
+          if (isRef(schema)) {
+            return elevateProperties(
+              resolve(schema).node as Oas3Schema | Oas3_1Schema | Oas2Schema
+            );
+          }
+
+          return Object.assign(
+            {},
+            schema.properties,
+            ...(schema.allOf?.map(elevateProperties) ?? []),
+            ...((schema as Oas3Schema).anyOf?.map(elevateProperties) ?? [])
+          );
+        };
+
+        const allProperties = elevateProperties(schema);
+
+        for (const [i, requiredProperty] of schema.required.entries()) {
+          if (!allProperties || allProperties[requiredProperty] === undefined) {
+            report({
+              message: `Required property '${requiredProperty}' is undefined.`,
+              location: location.child(['required', i]),
+            });
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/oas2/index.ts

@@ -41,6 +41,7 @@ import { ResponseContainsProperty } from './response-contains-property';
 import { ScalarPropertyMissingExample } from '../common/scalar-property-missing-example';
 import { RequiredStringPropertyMissingMinLength } from '../common/required-string-property-missing-min-length';
 import { SpecStrictRefs } from '../common/spec-strict-refs';
+import { NoRequiredSchemaPropertiesUndefined } from '../common/no-required-schema-properties-undefined';
 
 import type { Oas2RuleSet } from 'core/src/oas-types';
 
@@ -88,6 +89,7 @@ export const rules: Oas2RuleSet<'built-in'> = {
   'scalar-property-missing-example': ScalarPropertyMissingExample,
   'required-string-property-missing-min-length': RequiredStringPropertyMissingMinLength,
   'spec-strict-refs': SpecStrictRefs,
+  'no-required-schema-properties-undefined': NoRequiredSchemaPropertiesUndefined,
 };
 
 export const preprocessors = {};

package/src/rules/oas3/index.ts

@@ -53,6 +53,7 @@ import { RequiredStringPropertyMissingMinLength } from '../common/required-strin
 import { SpecStrictRefs } from '../common/spec-strict-refs';
 import { ComponentNameUnique } from './component-name-unique';
 import { ArrayParameterSerialization } from './array-parameter-serialization';
+import { NoRequiredSchemaPropertiesUndefined } from '../common/no-required-schema-properties-undefined';
 
 export const rules: Oas3RuleSet<'built-in'> = {
   spec: Spec,
@@ -110,6 +111,7 @@ export const rules: Oas3RuleSet<'built-in'> = {
   'spec-strict-refs': SpecStrictRefs,
   'component-name-unique': ComponentNameUnique,
   'array-parameter-serialization': ArrayParameterSerialization,
+  'no-required-schema-properties-undefined': NoRequiredSchemaPropertiesUndefined,
 };
 
 export const preprocessors = {};

package/src/types/redocly-yaml.ts

@@ -48,6 +48,7 @@ const builtInCommonOASRules = [
   'security-defined',
   'spec-strict-refs',
   'no-unresolved-refs',
+  'no-required-schema-properties-undefined',
 ] as const;
 
 export type BuiltInCommonOASRuleId = typeof builtInCommonOASRules[number];