@redocly/openapi-core 1.0.0 → 1.0.1

package/src/rules/oas2/__tests__/spec/paths.test.ts

@@ -0,0 +1,245 @@
+import { outdent } from 'outdent';
+import { lintDoc } from './utils';
+
+describe('OpenAPI Schema', () => {
+  it('should not report if Path object is valid ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        '/ping':
+          get:
+            responses:
+              '200':
+                description: example description
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report if Path object is empty ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths: {}
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should report if Path object is not present ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": "#/",
+          "message": "The field \`paths\` must be present on this level.",
+        },
+      ]
+    `);
+  });
+
+  it('should not report if Path object is empty ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths: {}
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  //Check: no error
+  it('should report if the field name is not begin with a forward slash (/) ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        'ping':
+          get:
+            responses:
+              '200':
+                description: example description
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": "#/paths/ping",
+          "message": "Property \`ping\` is not expected here.",
+        },
+      ]
+    `);
+  });
+
+  it('should report if paths are considered identical and invalid', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        /pets/{petId}:
+          get:
+            responses:
+              '200':
+                description: example description
+        /pets/{name}:
+          get:
+            responses:
+              '200':
+                description: example description
+    `;
+
+    expect(
+      await lintDoc(source, {
+        'paths-identical': 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report valid matching URLs', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        '/pets/{petId}':
+          get:
+            responses:
+              '200':
+                description: example description
+        '/pets/mine':
+           get:
+            responses:
+              '200':
+                description: example description
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report in case of ambiguous matching ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        '/{entity}/me':
+          get:
+            responses:
+              '200':
+                description: example description
+        '/books/{id}':
+          get:
+            responses:
+              '200':
+                description: example description
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report if Path Item is empty ', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        '/ping': {}
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report of a valid Parameter Object', async () => {
+    const source = outdent`
+      swagger: '2.0'
+      info:
+        title: Test
+        version: '1.0'
+
+      paths:
+        /pet:
+          parameters:
+            - name: Accept-Language
+              in: header
+              description: "test"
+              required: false
+              type: string
+              default: en-AU
+          post:
+            tags:
+              - pet
+            summary: Add a new pet to the store
+            description: Add new pet to the store inventory.
+            operationId: addPet
+            responses:
+              '405':
+                description: Invalid input
+    `;
+
+    expect(
+      await lintDoc(source, {
+        spec: 'error',
+      })
+    ).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/oas2/__tests__/spec/referenceableScalars.test.ts

@@ -0,0 +1,35 @@
+import { outdent } from 'outdent';
+import {
+  parseYamlToDocument,
+  replaceSourceWithRef,
+  makeConfig,
+} from '../../../../../__tests__/utils';
+import { lintDocument } from '../../../../lint';
+import { BaseResolver } from '../../../../resolve';
+
+describe('Referenceable scalars', () => {
+  it('should not report $ref description', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        swagger: '2.0'
+        info:
+          title: Test
+          version: '1.0'
+          description:
+            $ref: fixtures/description.md
+        paths: {}
+      `,
+      __dirname + '/foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        spec: 'error',
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/oas2/__tests__/spec/utils.ts

@@ -0,0 +1,32 @@
+import { StyleguideConfig, RuleConfig, resolveStyleguideConfig } from '../../../../config';
+import { parseYamlToDocument } from '../../../../../__tests__/utils';
+import { lintDocument } from '../../../../lint';
+import { BaseResolver } from '../../../../resolve';
+
+export async function lintDoc(
+  source: string,
+  rules: Record<string, RuleConfig> = { spec: 'error' }
+) {
+  const document = parseYamlToDocument(source, 'foobar.yaml');
+
+  const results = await lintDocument({
+    externalRefResolver: new BaseResolver(),
+    document,
+    config: new StyleguideConfig(
+      await resolveStyleguideConfig({
+        styleguideConfig: {
+          plugins: [],
+          extends: [],
+          rules,
+        },
+      })
+    ),
+  });
+
+  return results.map((res) => {
+    return {
+      message: res.message,
+      location: res.location[0].pointer || '',
+    };
+  });
+}

package/src/rules/oas2/boolean-parameter-prefixes.ts

@@ -0,0 +1,26 @@
+import { Oas2Rule } from '../../visitors';
+
+export type BooleanParameterPrefixesOptions = {
+  prefixes?: string[];
+};
+
+export const BooleanParameterPrefixes: Oas2Rule = (options: BooleanParameterPrefixesOptions) => {
+  const prefixes = options.prefixes || ['is', 'has'];
+  const regexp = new RegExp(`^(${prefixes.join('|')})[A-Z-_]`);
+  const wrappedPrefixes = prefixes.map((p) => `\`${p}\``);
+  const prefixesString =
+    wrappedPrefixes.length === 1
+      ? wrappedPrefixes[0]
+      : wrappedPrefixes.slice(0, -1).join(', ') + ' or ' + wrappedPrefixes[prefixes.length - 1];
+
+  return {
+    Parameter(param, { report, location }) {
+      if (param.type === 'boolean' && !regexp.test(param.name)) {
+        report({
+          message: `Boolean parameter \`${param.name}\` should have ${prefixesString} prefix.`,
+          location: location.child('name'),
+        });
+      }
+    },
+  };
+};

package/src/rules/oas2/index.ts

@@ -0,0 +1,91 @@
+import { Oas2Rule } from '../../visitors';
+import { OasSpec } from '../common/spec';
+import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
+import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
+import { InfoContact } from '../common/info-contact';
+import { InfoLicense } from '../common/info-license';
+import { InfoLicenseUrl } from '../common/info-license-url';
+import { BooleanParameterPrefixes } from './boolean-parameter-prefixes';
+import { TagDescription } from '../common/tag-description';
+import { TagsAlphabetical } from '../common/tags-alphabetical';
+import { PathsKebabCase } from '../common/paths-kebab-case';
+import { NoEnumTypeMismatch } from '../common/no-enum-type-mismatch';
+import { NoPathTrailingSlash } from '../common/no-path-trailing-slash';
+import { Operation2xxResponse } from '../common/operation-2xx-response';
+import { Operation4xxResponse } from '../common/operation-4xx-response';
+import { Assertions } from '../common/assertions';
+import { OperationIdUnique } from '../common/operation-operationId-unique';
+import { OperationParametersUnique } from '../common/operation-parameters-unique';
+import { PathParamsDefined } from '../common/path-params-defined';
+import { OperationTagDefined } from '../common/operation-tag-defined';
+import { PathDeclarationMustExist } from '../common/path-declaration-must-exist';
+import { OperationIdUrlSafe } from '../common/operation-operationId-url-safe';
+import { OperationDescription } from '../common/operation-description';
+import { PathNotIncludeQuery } from '../common/path-not-include-query';
+import { ParameterDescription } from '../common/parameter-description';
+import { OperationSingularTag } from '../common/operation-singular-tag';
+import { SecurityDefined } from '../common/security-defined';
+import { NoUnresolvedRefs } from '../no-unresolved-refs';
+import { PathHttpVerbsOrder } from '../common/path-http-verbs-order';
+import { NoIdenticalPaths } from '../common/no-identical-paths';
+import { OperationOperationId } from '../common/operation-operationId';
+import { OperationSummary } from '../common/operation-summary';
+import { NoAmbiguousPaths } from '../common/no-ambiguous-paths';
+import { NoHttpVerbsInPaths } from '../common/no-http-verbs-in-paths';
+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';
+import { RequiredStringPropertyMissingMinLength } from '../common/required-string-property-missing-min-length';
+import { SpecStrictRefs } from '../common/spec-strict-refs';
+
+export const rules = {
+  spec: OasSpec as Oas2Rule,
+  'no-invalid-schema-examples': NoInvalidSchemaExamples,
+  'no-invalid-parameter-examples': NoInvalidParameterExamples,
+  'info-contact': InfoContact as Oas2Rule,
+  'info-license': InfoLicense as Oas2Rule,
+  'info-license-url': InfoLicenseUrl as Oas2Rule,
+  'tag-description': TagDescription as Oas2Rule,
+  'tags-alphabetical': TagsAlphabetical as Oas2Rule,
+  'paths-kebab-case': PathsKebabCase as Oas2Rule,
+  'no-enum-type-mismatch': NoEnumTypeMismatch as Oas2Rule,
+  'boolean-parameter-prefixes': BooleanParameterPrefixes as Oas2Rule,
+  'no-path-trailing-slash': NoPathTrailingSlash as Oas2Rule,
+  'operation-2xx-response': Operation2xxResponse as Oas2Rule,
+  'operation-4xx-response': Operation4xxResponse as Oas2Rule,
+  assertions: Assertions as Oas2Rule,
+  'operation-operationId-unique': OperationIdUnique as Oas2Rule,
+  'operation-parameters-unique': OperationParametersUnique as Oas2Rule,
+  'path-parameters-defined': PathParamsDefined as Oas2Rule,
+  'operation-tag-defined': OperationTagDefined as Oas2Rule,
+  'path-declaration-must-exist': PathDeclarationMustExist as Oas2Rule,
+  'operation-operationId-url-safe': OperationIdUrlSafe as Oas2Rule,
+  'operation-operationId': OperationOperationId as Oas2Rule,
+  'operation-summary': OperationSummary as Oas2Rule,
+  'operation-description': OperationDescription as Oas2Rule,
+  'path-not-include-query': PathNotIncludeQuery as Oas2Rule,
+  'path-params-defined': PathParamsDefined as Oas2Rule,
+  'parameter-description': ParameterDescription as Oas2Rule,
+  'operation-singular-tag': OperationSingularTag as Oas2Rule,
+  'security-defined': SecurityDefined as Oas2Rule,
+  'no-unresolved-refs': NoUnresolvedRefs as Oas2Rule,
+  'no-identical-paths': NoIdenticalPaths as Oas2Rule,
+  'no-ambiguous-paths': NoAmbiguousPaths as Oas2Rule,
+  'path-http-verbs-order': PathHttpVerbsOrder as Oas2Rule,
+  'no-http-verbs-in-paths': NoHttpVerbsInPaths as Oas2Rule,
+  'path-excludes-patterns': PathExcludesPatterns as Oas2Rule,
+  '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,
+  'required-string-property-missing-min-length': RequiredStringPropertyMissingMinLength,
+  'spec-strict-refs': SpecStrictRefs,
+};
+
+export const preprocessors = {};

package/src/rules/oas2/remove-unused-components.ts

@@ -0,0 +1,81 @@
+import { Oas2Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+import { Oas2Components } from '../../typings/swagger';
+import { isEmptyObject } from '../../utils';
+
+export const RemoveUnusedComponents: Oas2Rule = () => {
+  const components = new Map<
+    string,
+    { used: boolean; componentType?: keyof Oas2Components; name: string }
+  >();
+
+  function registerComponent(
+    location: Location,
+    componentType: keyof Oas2Components,
+    name: string
+  ): void {
+    components.set(location.absolutePointer, {
+      used: components.get(location.absolutePointer)?.used || false,
+      componentType,
+      name,
+    });
+  }
+
+  return {
+    ref: {
+      leave(ref, { type, resolve, key }) {
+        if (['Schema', 'Parameter', 'Response', 'SecurityScheme'].includes(type.name)) {
+          const resolvedRef = resolve(ref);
+          if (!resolvedRef.location) return;
+          components.set(resolvedRef.location.absolutePointer, {
+            used: true,
+            name: key.toString(),
+          });
+        }
+      },
+    },
+    Root: {
+      leave(root, ctx) {
+        const data = ctx.getVisitorData() as { removedCount: number };
+        data.removedCount = 0;
+
+        const rootComponents = new Set<keyof Oas2Components>();
+        components.forEach((usageInfo) => {
+          const { used, name, componentType } = usageInfo;
+          if (!used && componentType) {
+            rootComponents.add(componentType);
+            delete root[componentType]![name];
+            data.removedCount++;
+          }
+        });
+        for (const component of rootComponents) {
+          if (isEmptyObject(root[component])) {
+            delete root[component];
+          }
+        }
+      },
+    },
+    NamedSchemas: {
+      Schema(schema, { location, key }) {
+        if (!schema.allOf) {
+          registerComponent(location, 'definitions', key.toString());
+        }
+      },
+    },
+    NamedParameters: {
+      Parameter(_parameter, { location, key }) {
+        registerComponent(location, 'parameters', key.toString());
+      },
+    },
+    NamedResponses: {
+      Response(_response, { location, key }) {
+        registerComponent(location, 'responses', key.toString());
+      },
+    },
+    NamedSecuritySchemes: {
+      SecurityScheme(_securityScheme, { location, key }) {
+        registerComponent(location, 'securityDefinitions', key.toString());
+      },
+    },
+  };
+};

package/src/rules/oas2/request-mime-type.ts

@@ -0,0 +1,16 @@
+import type { Oas2Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import { validateMimeType } from '../../utils';
+
+export const RequestMimeType: Oas2Rule = ({ allowedValues }) => {
+  return {
+    Root(root, ctx: UserContext) {
+      validateMimeType({ type: 'consumes', value: root }, ctx, allowedValues);
+    },
+    Operation: {
+      leave(operation, ctx: UserContext) {
+        validateMimeType({ type: 'consumes', value: operation }, ctx, allowedValues);
+      },
+    },
+  };
+};

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/oas2/response-mime-type.ts

@@ -0,0 +1,16 @@
+import type { Oas2Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import { validateMimeType } from '../../utils';
+
+export const ResponseMimeType: Oas2Rule = ({ allowedValues }) => {
+  return {
+    Root(root, ctx: UserContext) {
+      validateMimeType({ type: 'produces', value: root }, ctx, allowedValues);
+    },
+    Operation: {
+      leave(operation, ctx: UserContext) {
+        validateMimeType({ type: 'produces', value: operation }, ctx, allowedValues);
+      },
+    },
+  };
+};

package/src/rules/oas3/__tests__/boolean-parameter-prefixes.test.ts

@@ -0,0 +1,111 @@
+import { outdent } from 'outdent';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { lintDocument } from '../../../lint';
+import { BaseResolver } from '../../../resolve';
+
+describe('oas3 boolean-parameter-prefixes', () => {
+  it('should report on boolean param without prefix', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: path
+              schema:
+                type: boolean
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'boolean-parameter-prefixes': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1test/parameters/0/name",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Boolean parameter \`a\` should have \`is\` or \`has\` prefix.",
+          "ruleId": "boolean-parameter-prefixes",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on boolean param with prefix', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test':
+              parameters:
+                - name: hasA
+                  in: path
+                  schema:
+                    type: boolean
+                - name: isA
+                  in: path
+                  schema:
+                    type: boolean
+                - name: has_a
+                  in: path
+                  schema:
+                    type: boolean
+                - name: is-a
+                  in: path
+                  schema:
+                    type: boolean
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'boolean-parameter-prefixes': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on boolean param with custom prefix', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test':
+              parameters:
+              - name: should-a
+                in: query
+                schema:
+                  type: boolean
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'boolean-parameter-prefixes': {
+          severity: 'error',
+          prefixes: ['should'],
+        },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});