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

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(),
+              });
+            }
+          }
+        },
+      },
+    },
+  };
+};

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

@@ -0,0 +1,273 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas3 response-contains-header', () => {
+  it('should report a response object not containing the header', async () => {
+    const document = parseYamlToDocument(outdent`
+      openapi: 3.0.3
+      info:
+        version: 3.0.0
+      paths:
+        /store/subscribe:
+          post:
+            responses:
+              '200':
+                description: successful operation
+                headers:
+                  X-Rate-Limit:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+		`);
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: { '200': ['Content-Length'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1store~1subscribe/post/responses/200/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "openapi: 3.0.3
+      info:
+        version: 3.0.0
+      paths:
+        /store/subscribe:
+          post:
+            responses:
+              '200':
+                description: successful operation
+                headers:
+                  X-Rate-Limit:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"Content-Length\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should report response objects not containing headers for a subset of status codes', async () => {
+    const document = parseYamlToDocument(outdent`
+      openapi: 3.0.3
+      info:
+        version: 3.0.0
+      paths:
+        /store/subscribe:
+          post:
+            responses:
+              '200':
+                description: successful operation
+                headers:
+                  X-Rate-Limit:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+              400:
+                description: error
+                headers:
+                  AccessForbidden:
+                    description: Access forbidden
+                    content:
+                      application/json:
+                        schema:
+                          type: object
+                          properties:
+                            status:
+                              type: integer
+                              description: The HTTP status code.
+                            error:
+                              type: string
+    `);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: {
+            '2XX': ['x-request-id'],
+            '400': ['Content-Length'],
+          },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1store~1subscribe/post/responses/200/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "openapi: 3.0.3
+      info:
+        version: 3.0.0
+      paths:
+        /store/subscribe:
+          post:
+            responses:
+              '200':
+                description: successful operation
+                headers:
+                  X-Rate-Limit:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+              400:
+                description: error
+                headers:
+                  AccessForbidden:
+                    description: Access forbidden
+                    content:
+                      application/json:
+                        schema:
+                          type: object
+                          properties:
+                            status:
+                              type: integer
+                              description: The HTTP status code.
+                            error:
+                              type: string",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"x-request-id\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1store~1subscribe/post/responses/400/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "openapi: 3.0.3
+      info:
+        version: 3.0.0
+      paths:
+        /store/subscribe:
+          post:
+            responses:
+              '200':
+                description: successful operation
+                headers:
+                  X-Rate-Limit:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+              400:
+                description: error
+                headers:
+                  AccessForbidden:
+                    description: Access forbidden
+                    content:
+                      application/json:
+                        schema:
+                          type: object
+                          properties:
+                            status:
+                              type: integer
+                              description: The HTTP status code.
+                            error:
+                              type: string",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"Content-Length\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report response objects containing specified headers', async () => {
+    const document = parseYamlToDocument(outdent`
+      openapi: 3.0.3
+      info:
+        version: 3.0.0
+      paths:
+        /store/subscribe:
+          post:
+            responses:
+              '200':
+                description: successful operation
+                headers:
+                  X-Rate-Limit:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+                  x-request-id:
+                    description: Request ID
+                    schema:
+                      type: string
+              400:
+                description: error
+                headers:
+                  AccessForbidden:
+                    description: Access forbidden
+                    content:
+                      application/json:
+                        schema:
+                          type: object
+                          properties:
+                            status:
+                              type: integer
+                              description: The HTTP status code.
+                            error:
+                              type: string
+                  Content-Length:
+                    description: The number of bytes in the file
+                    schema:
+                      type: integer
+    `);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: {
+            '2xx': ['x-request-id'],
+            '400': ['Content-Length'],
+          },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+});