@redocly/openapi-core 1.0.0-beta.96 → 1.0.0-beta.99

package/src/rules/common/__tests__/scalar-property-missing-example.test.ts

@@ -0,0 +1,207 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas3 scalar-property-missing-example', () => {
+  it('should report on a scalar property missing example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components/schemas/User/properties/email",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Scalar property should have \\"example\\" defined.",
+          "ruleId": "scalar-property-missing-example",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+});
+
+describe('Oas3.1 scalar-property-missing-example', () => {
+  it('should report on a scalar property missing example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components/schemas/User/properties/email",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Scalar property should have \\"example\\" or \\"examples\\" defined.",
+          "ruleId": "scalar-property-missing-example",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on a scalar property with an example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+                  example: john.smith@example.com
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on a scalar property with an examples', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+                  examples: 
+                  - john.smith@example.com
+                  - other@example.com
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on a non-scalar property missing an example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            Pet:
+              type: object
+              required:
+                - photoUrls
+              properties:
+                photoUrls:
+                  description: The list of URL to a cute photos featuring pet
+                  type: array
+                  maxItems: 20
+                  xml:
+                    name: photoUrl
+                    wrapped: true
+                  items:
+                    type: string
+                    format: url
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on a scalar property of binary format missing an example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                responses:
+                  type: string
+                  format: binary
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/common/response-contains-header.ts

@@ -0,0 +1,30 @@
+import { Oas2Rule, Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3Response } from '../../typings/openapi';
+import { Oas2Response } from '../../typings/swagger';
+import { getMatchingStatusCodeRange } from '../../utils';
+
+export const ResponseContainsHeader: Oas3Rule | Oas2Rule = (options) => {
+  const names: Record<string, string[]> = options.names || {};
+  return {
+    Operation: {
+      Response: {
+        enter: (response: Oas2Response | Oas3Response, { report, location, key }: UserContext) => {
+          const expectedHeaders =
+            names[key] ||
+            names[getMatchingStatusCodeRange(key)] ||
+            names[getMatchingStatusCodeRange(key).toLowerCase()] ||
+            [];
+          for (const expectedHeader of expectedHeaders) {
+            if (!response.headers?.[expectedHeader]) {
+              report({
+                message: `Response object must contain a "${expectedHeader}" header.`,
+                location: location.child('headers').key(),
+              });
+            }
+          }
+        },
+      },
+    },
+  };
+};

package/src/rules/common/scalar-property-missing-example.ts

@@ -0,0 +1,55 @@
+import type { Oas2Rule, Oas3Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import type { Oas2Schema } from '../../typings/swagger';
+import type { Oas3Schema, Oas3_1Schema } from '../../typings/openapi';
+import { OasVersion } from '../../oas-types';
+
+const SCALAR_TYPES = ['string', 'integer', 'number', 'boolean', 'null'];
+
+export const ScalarPropertyMissingExample: Oas3Rule | Oas2Rule = () => {
+  return {
+    SchemaProperties(
+      properties: { [name: string]: Oas2Schema | Oas3Schema | Oas3_1Schema },
+      { report, location, oasVersion, resolve }: UserContext,
+    ) {
+      for (const propName of Object.keys(properties)) {
+        const propSchema = resolve(properties[propName]).node;
+
+        if (!propSchema || !isScalarSchema(propSchema)) {
+          continue;
+        }
+
+        if (!propSchema.example && !(propSchema as Oas3_1Schema).examples) {
+          report({
+            message: `Scalar property should have "example"${
+              oasVersion === OasVersion.Version3_1 ? ' or "examples"' : ''
+            } defined.`,
+            location: location.child(propName).key(),
+          });
+        }
+      }
+    },
+  };
+};
+
+function isScalarSchema(schema: Oas2Schema | Oas3Schema | Oas3_1Schema) {
+  if (!schema.type) {
+    return false;
+  }
+
+  if (schema.allOf || (schema as Oas3Schema).anyOf || (schema as Oas3Schema).oneOf) {
+    // Skip allOf/oneOf/anyOf as it's complicated to validate it right now.
+    // We need core support for checking contrstrains through those keywords.
+    return false;
+  }
+
+  if (schema.format === 'binary') {
+    return false;
+  }
+
+  if (Array.isArray(schema.type)) {
+    return schema.type.every((t) => SCALAR_TYPES.includes(t));
+  }
+
+  return SCALAR_TYPES.includes(schema.type);
+}

package/src/rules/oas2/__tests__/response-contains-header.test.ts

@@ -0,0 +1,174 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas2 response-contains-header', () => {
+  it('should report a response object not containing the header', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Location:
+                    description: Location of created Account
+                    type: string
+              '404':
+                description: User not found
+    `);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: { '2xx': ['Content-Length'], '4xx': ['Content-Length'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1accounts~1{accountId}/get/responses/201/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Location:
+                    description: Location of created Account
+                    type: string
+              '404':
+                description: User not found",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"Content-Length\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1accounts~1{accountId}/get/responses/404/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Location:
+                    description: Location of created Account
+                    type: string
+              '404':
+                description: User not found",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"Content-Length\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report a response object containing the header nor not applicable', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Length:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+              '404':
+                description: User not found
+		`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: { '2xx': ['Content-Length'], '400': ['Content-Length'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report a response object when there is no `names` section defined', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '404':
+                description: User not found
+		`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/oas2/__tests__/response-contains-property.test.ts

@@ -0,0 +1,155 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas2 response-contains-property', () => {
+  it('should report a response object not containing the property', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '200':
+                description: Account object returned
+                schema:
+                  type: object
+                  properties:
+                    created_at:
+                      description: Account creation date/time
+                      format: date-time
+                      type: string
+                    owner_email:
+                      description: Account Owner email
+                      type: string
+              '404':
+                description: User not found
+			`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-property': {
+          severity: 'error',
+          names: { '2xx': ['id'], '4xx': ['id'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1accounts~1{accountId}/get/responses/200/schema/properties",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '200':
+                description: Account object returned
+                schema:
+                  type: object
+                  properties:
+                    created_at:
+                      description: Account creation date/time
+                      format: date-time
+                      type: string
+                    owner_email:
+                      description: Account Owner email
+                      type: string
+              '404':
+                description: User not found",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a top-level \\"id\\" property.",
+          "ruleId": "response-contains-property",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report a response object containing the expected property', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '200':
+                description: Account object returned
+                schema:
+                  type: object
+                  properties:
+                    created_at:
+                      description: Account creation date/time
+                      format: date-time
+                      type: string
+                    id: some-id
+              '404':
+                description: User not found
+                id: some-id
+			`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-property': {
+          severity: 'error',
+          names: { '200': ['id'], '4xx': ['id'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report a response object when there is no `names` section defined', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '404':
+                description: User not found
+    `);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-property': {
+          severity: 'error',
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/oas2/index.ts

@@ -37,6 +37,9 @@ import { PathExcludesPatterns } from '../common/path-excludes-patterns';
 import { RequestMimeType } from './request-mime-type';
 import { ResponseMimeType } from './response-mime-type';
 import { PathSegmentPlural } from '../common/path-segment-plural';
+import { ResponseContainsHeader } from '../common/response-contains-header';
+import { ResponseContainsProperty } from './response-contains-property';
+import { ScalarPropertyMissingExample } from '../common/scalar-property-missing-example';
 
 export const rules = {
   spec: OasSpec as Oas2Rule,
@@ -78,6 +81,9 @@ export const rules = {
   'request-mime-type': RequestMimeType as Oas2Rule,
   'response-mime-type': ResponseMimeType as Oas2Rule,
   'path-segment-plural': PathSegmentPlural as Oas2Rule,
+  'response-contains-header': ResponseContainsHeader as Oas2Rule,
+  'response-contains-property': ResponseContainsProperty as Oas2Rule,
+  'scalar-property-missing-example': ScalarPropertyMissingExample,
 };
 
 export const preprocessors = {};

package/src/rules/oas2/response-contains-property.ts

@@ -0,0 +1,36 @@
+import { Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { getMatchingStatusCodeRange } from '../../utils';
+
+export const ResponseContainsProperty: Oas2Rule = (options) => {
+  const names: Record<string, string[]> = options.names || {};
+  let key: string | number;
+  return {
+    Operation: {
+      Response: {
+        skip: (_response, key) => {
+          return `${key}` === '204';
+        },
+        enter: (_response, ctx: UserContext) => {
+          key = ctx.key;
+        },
+        Schema(schema, { report, location }) {
+          if (schema.type !== 'object') return;
+          const expectedProperties =
+            names[key] ||
+            names[getMatchingStatusCodeRange(key)] ||
+            names[getMatchingStatusCodeRange(key).toLowerCase()] ||
+            [];
+          for (const expectedProperty of expectedProperties) {
+            if (!schema.properties?.[expectedProperty]) {
+              report({
+                message: `Response object must contain a top-level "${expectedProperty}" property.`,
+                location: location.child('properties').key(),
+              });
+            }
+          }
+        },
+      },
+    },
+  };
+};