@redocly/openapi-core 1.0.0-beta.64 → 1.0.0-beta.68

package/src/index.ts

@@ -1,4 +1,4 @@
-export { BundleOutputFormat, readFileFromUrl } from './utils';
+export { BundleOutputFormat, readFileFromUrl, slash } from './utils';
 export { Oas3_1Types } from './types/oas3_1';
 export { Oas3Types } from './types/oas3';
 export { Oas2Types } from './types/oas2';

package/src/ref-utils.ts

@@ -1,5 +1,3 @@
-import { sep as platformDependentSeparator } from 'path';
-
 import { Source } from './resolve';
 import { OasRef } from './typings/openapi';
 
@@ -61,7 +59,7 @@ export function pointerBaseName(pointer: string) {
 }
 
 export function refBaseName(ref: string) {
-  const parts = ref.split(platformDependentSeparator);
+  const parts = ref.split(/[\/\\]/); // split by '\' and '/'
   return parts[parts.length - 1].split('.')[0];
 }
 

package/src/rules/common/__tests__/info-license.test.ts

@@ -27,7 +27,7 @@ describe('Oas3 info-license', () => {
           "location": Array [
             Object {
               "pointer": "#/info",
-              "reportOnKey": false,
+              "reportOnKey": true,
               "source": "foobar.yaml",
             },
           ],

package/src/rules/common/__tests__/operation-4xx-response.test.ts

@@ -0,0 +1,108 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef } from '../../../../__tests__/utils';
+import { makeConfig } from '../../__tests__/config';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas3 operation-4xx-response', () => {
+  it('should report missing 4xx response', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test':
+              put:
+                responses:
+                  200:
+                    description: ok response
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1test/put/responses",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Operation must have at least one \`4xx\` response.",
+          "ruleId": "operation-4xx-response",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report for present 4xx response', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test/':
+              put:
+                responses:
+                  400:
+                    description: error response
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should report if default is present but missing 4xx response', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test/':
+              put:
+                responses:
+                  default:
+                    description: some default response
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1test~1/put/responses",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Operation must have at least one \`4xx\` response.",
+          "ruleId": "operation-4xx-response",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+});

package/src/rules/common/info-description-override.ts

@@ -0,0 +1,24 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { readFileAsStringSync } from '../../utils';
+import { UserContext } from '../../walk';
+
+export const InfoDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ filePath }) => {
+  return {
+    Info: {
+      leave(info, { report, location }: UserContext) {
+        if (!filePath)
+          throw new Error(
+            `Parameter "filePath" is not provided for "info-description-override" rule`,
+          );
+        try {
+          info.description = readFileAsStringSync(filePath);
+        } catch (e) {
+          report({
+            message: `Failed to read markdown override file for "info.description".\n${e.message}`,
+            location: location.child('description'),
+          });
+        }
+      },
+    },
+  };
+};

package/src/rules/common/info-license-url.ts

@@ -7,6 +7,7 @@ export const InfoLicense: Oas3Rule | Oas2Rule = () => {
       if (!info.license) {
         report({
           message: missingRequiredField('Info', 'license'),
+          location: { reportOnKey: true }
         });
       }
     },

package/src/rules/common/no-http-verbs-in-paths.ts

@@ -0,0 +1,36 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2PathItem } from '../../typings/swagger';
+import { Oas3PathItem } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+import { isPathParameter, splitCamelCaseIntoWords } from '../../utils';
+
+const httpMethods = ['get', 'head', 'post', 'put', 'patch', 'delete', 'options', 'trace'];
+
+export const NoHttpVerbsInPaths: Oas3Rule | Oas2Rule = ({ splitIntoWords }) => {
+  return {
+    PathItem(_path: Oas2PathItem | Oas3PathItem, { key, report, location }: UserContext) {
+      const pathKey = key.toString();
+      if (!pathKey.startsWith('/')) return;
+      const pathSegments = pathKey.split('/');
+
+      for (const pathSegment of pathSegments) {
+        if (!pathSegment || isPathParameter(pathSegment)) continue;
+
+        const isHttpMethodIncluded = (method: string) => {
+          return splitIntoWords
+            ? splitCamelCaseIntoWords(pathSegment).has(method)
+            : pathSegment.toLocaleLowerCase().includes(method);
+        };
+
+        for (const method of httpMethods) {
+          if (isHttpMethodIncluded(method)) {
+            report({
+              message: `path \`${pathKey}\` should not contain http verb ${method}`,
+              location: location.key(),
+            });
+          }
+        }
+      }
+    },
+  };
+};

package/src/rules/common/operation-4xx-response.ts

@@ -0,0 +1,17 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const Operation4xxResponse: Oas3Rule | Oas2Rule = () => {
+  return {
+    ResponsesMap(responses: Record<string, object>, { report }: UserContext) {
+      const codes = Object.keys(responses);
+
+      if (!codes.some((code) => /4[Xx0-9]{2}/.test(code))) {
+        report({
+          message: 'Operation must have at least one `4xx` response.',
+          location: { reportOnKey: true },
+        });
+      }
+    },
+  };
+};

package/src/rules/common/operation-description-override.ts

@@ -0,0 +1,30 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+import { readFileAsStringSync } from '../../utils';
+import { UserContext } from '../../walk';
+
+export const OperationDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ operationIds }) => {
+  return {
+    Operation: {
+      leave(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+        if (!operation.operationId) return;
+        if (!operationIds)
+          throw new Error(
+            `Parameter "operationIds" is not provided for "operation-description-override" rule`,
+          );
+        const operationId = operation.operationId;
+        if (operationIds[operationId]) {
+          try {
+            operation.description = readFileAsStringSync(operationIds[operationId]);
+          } catch (e) {
+            report({
+              message: `Failed to read markdown override file for operation "${operationId}".\n${e.message}`,
+              location: location.child('operationId').key(),
+            });
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/common/path-excludes-patterns.ts

@@ -0,0 +1,23 @@
+import { Oas2Rule, Oas3Rule } from '../../visitors';
+import { Oas2PathItem } from '../../typings/swagger';
+import { Oas3PathItem } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const PathExcludesPatterns: Oas3Rule | Oas2Rule = ({ patterns }) => {
+  return {
+    PathItem(_path: Oas2PathItem | Oas3PathItem, { report, key, location }: UserContext) {
+      if (!patterns)
+        throw new Error(`Parameter "patterns" is not provided for "path-excludes-patterns" rule`);
+      const pathKey = key.toString();
+      if (pathKey.startsWith('/')) {
+        const matches = patterns.filter((pattern: string) => pathKey.match(pattern));
+        for (const match of matches) {
+          report({
+            message: `path \`${pathKey}\` should not match regex pattern: \`${match}\``,
+            location: location.key(),
+          });
+        }
+      }
+    },
+  };
+};

package/src/rules/common/path-segment-plural.ts

@@ -0,0 +1,31 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { isPathParameter, isSingular } from '../../utils';
+
+export const PathSegmentPlural: Oas3Rule | Oas2Rule = (opts) => {
+  const { ignoreLastPathSegment, exceptions } = opts;
+  return {
+    PathItem: {
+      leave(_path: any, { report, key, location }: UserContext) {
+        const pathKey = key.toString();
+        if (pathKey.startsWith('/')) {
+          const pathSegments = pathKey.split('/');
+          pathSegments.shift();
+          if (ignoreLastPathSegment && pathSegments.length > 1) {
+            pathSegments.pop();
+          }
+
+          for (const pathSegment of pathSegments) {
+            if (exceptions && exceptions.includes(pathSegment)) continue;
+            if (!isPathParameter(pathSegment) && isSingular(pathSegment)) {
+              report({
+                message: `path segment \`${pathSegment}\` should be plural.`,
+                location: location.key(),
+              });
+            }
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/common/tag-description-override.ts

@@ -0,0 +1,25 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { readFileAsStringSync } from '../../utils';
+import { UserContext } from '../../walk';
+
+export const TagDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ tagNames }) => {
+  return {
+    Tag: {
+      leave(tag, { report }: UserContext) {
+        if (!tagNames)
+          throw new Error(
+            `Parameter "tagNames" is not provided for "tag-description-override" rule`,
+          );
+        if (tagNames[tag.name]) {
+          try {
+            tag.description = readFileAsStringSync(tagNames[tag.name]);
+          } catch (e) {
+            report({
+              message: `Failed to read markdown override file for tag "${tag.name}".\n${e.message}`,
+            });
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/oas2/index.ts

@@ -10,6 +10,7 @@ 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 { OperationIdUnique } from '../common/operation-operationId-unique';
 import { OperationParametersUnique } from '../common/operation-parameters-unique';
 import { PathParamsDefined } from '../common/path-params-defined';
@@ -29,6 +30,14 @@ 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 { OperationDescriptionOverride } from '../common/operation-description-override';
+import { TagDescriptionOverride } from '../common/tag-description-override';
+import { InfoDescriptionOverride } from '../common/info-description-override';
 
 export const rules = {
   spec: OasSpec as Oas2Rule,
@@ -43,6 +52,7 @@ export const rules = {
   '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,
   'operation-operationId-unique': OperationIdUnique as Oas2Rule,
   'operation-parameters-unique': OperationParametersUnique as Oas2Rule,
   'path-parameters-defined': PathParamsDefined as Oas2Rule,
@@ -61,9 +71,17 @@ export const rules = {
   '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,
 };
 
 export const preprocessors = {};
 export const decorators = {
   'registry-dependencies': RegistryDependencies as Oas2Decorator,
+  'operation-description-override': OperationDescriptionOverride as Oas2Decorator,
+  'tag-description-override': TagDescriptionOverride as Oas2Decorator,
+  'info-description-override': InfoDescriptionOverride as Oas2Decorator,
 };

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

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

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

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

package/src/rules/oas3/__tests__/no-server-trailing-slash.test.ts

@@ -58,4 +58,23 @@ describe('Oas3 oas3-no-server-trailing-slash', () => {
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
   });
+
+  it('oas3-no-server-trailing-slash: should not report on server object with no trailing slash if the url is root', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          servers:
+            - url: /
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'no-server-trailing-slash': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
 });

package/src/rules/oas3/index.ts

@@ -1,6 +1,8 @@
 import { Oas3RuleSet } from '../../oas-types';
+import { Oas3Decorator } from '../../visitors';
 import { OasSpec } from '../common/spec';
 import { Operation2xxResponse } from '../common/operation-2xx-response';
+import { Operation4xxResponse } from '../common/operation-4xx-response';
 import { OperationIdUnique } from '../common/operation-operationId-unique';
 import { OperationParametersUnique } from '../common/operation-parameters-unique';
 import { PathParamsDefined } from '../common/path-params-defined';
@@ -37,8 +39,14 @@ import { OperationOperationId } from '../common/operation-operationId';
 import { OperationSummary } from '../common/operation-summary';
 import { NoAmbiguousPaths } from '../common/no-ambiguous-paths';
 import { NoEmptyEnumServers } from './no-servers-empty-enum';
-
-import { Oas3Decorator } from '../../visitors';
+import { NoHttpVerbsInPaths } from '../common/no-http-verbs-in-paths';
+import { RequestMimeType } from './request-mime-type';
+import { ResponseMimeType } from './response-mime-type';
+import { PathSegmentPlural } from '../common/path-segment-plural';
+import { OperationDescriptionOverride } from '../common/operation-description-override';
+import { TagDescriptionOverride } from '../common/tag-description-override';
+import { InfoDescriptionOverride } from '../common/info-description-override';
+import { PathExcludesPatterns } from '../common/path-excludes-patterns';
 
 export const rules = {
   spec: OasSpec,
@@ -47,6 +55,7 @@ export const rules = {
   'info-license': InfoLicense,
   'info-license-url': InfoLicenseUrl,
   'operation-2xx-response': Operation2xxResponse,
+  'operation-4xx-response': Operation4xxResponse,
   'operation-operationId-unique': OperationIdUnique,
   'operation-parameters-unique': OperationParametersUnique,
   'path-parameters-defined': PathParamsDefined,
@@ -78,11 +87,19 @@ export const rules = {
   'no-identical-paths': NoIdenticalPaths,
   'no-ambiguous-paths': NoAmbiguousPaths,
   'no-undefined-server-variable': NoUndefinedServerVariable,
-  'no-servers-empty-enum': NoEmptyEnumServers
+  'no-servers-empty-enum': NoEmptyEnumServers,
+  'no-http-verbs-in-paths': NoHttpVerbsInPaths,
+  'path-excludes-patterns': PathExcludesPatterns,
+  'request-mime-type': RequestMimeType,
+  'response-mime-type': ResponseMimeType,
+  'path-segment-plural': PathSegmentPlural,
 } as Oas3RuleSet;
 
 export const preprocessors = {};
 
 export const decorators = {
   'registry-dependencies': RegistryDependencies as Oas3Decorator,
+  'operation-description-override': OperationDescriptionOverride as Oas3Decorator,
+  'tag-description-override': TagDescriptionOverride as Oas3Decorator,
+  'info-description-override': InfoDescriptionOverride as Oas3Decorator,
 };

package/src/rules/oas3/no-server-trailing-slash.ts

@@ -4,7 +4,7 @@ export const NoServerTrailingSlash: Oas3Rule = () => {
   return {
     Server(server, { report, location }) {
       if (!server.url) return;
-      if (server.url.endsWith('/')) {
+      if (server.url.endsWith('/') && server.url !== '/') {
         report({
           message: 'Server `url` should not have a trailing slash.',
           location: location.child(['url']),

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

@@ -0,0 +1,31 @@
+import { Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3RequestBody, Oas3Response } from '../../typings/openapi';
+import { validateMimeTypeOAS3 } from '../../utils';
+
+export const RequestMimeType: Oas3Rule = ({ allowedValues }) => {
+  return {
+    PathMap: {
+      RequestBody: {
+        leave(requestBody: Oas3RequestBody, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'consumes', value: requestBody }, ctx, allowedValues);
+        },
+      },
+      Callback: {
+        RequestBody() {},
+        Response: {
+          leave(response: Oas3Response, ctx: UserContext) {
+            validateMimeTypeOAS3({ type: 'consumes', value: response }, ctx, allowedValues);
+          },
+        },
+      },
+    },
+    WebhooksMap: {
+      Response: {
+        leave(response: Oas3Response, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'consumes', value: response }, ctx, allowedValues);
+        },
+      },
+    },
+  };
+};

package/src/rules/oas3/response-mime-type.ts

@@ -0,0 +1,31 @@
+import { Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3RequestBody, Oas3Response } from '../../typings/openapi';
+import { validateMimeTypeOAS3 } from '../../utils';
+
+export const ResponseMimeType: Oas3Rule = ({ allowedValues }) => {
+  return {
+    PathMap: {
+      Response: {
+        leave(response: Oas3Response, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'produces', value: response }, ctx, allowedValues);
+        },
+      },
+      Callback: {
+        Response() {},
+        RequestBody: {
+          leave(requestBody: Oas3RequestBody, ctx: UserContext) {
+            validateMimeTypeOAS3({ type: 'produces', value: requestBody }, ctx, allowedValues);
+          },
+        },
+      },
+    },
+    WebhooksMap: {
+      RequestBody: {
+        leave(requestBody: Oas3RequestBody, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'produces', value: requestBody }, ctx, allowedValues);
+        },
+      },
+    },
+  };
+};

package/src/rules/utils.ts

@@ -79,4 +79,4 @@ export function getSuggest(given: string, variants: string[]): string[] {
 
   // if (bestMatch.distance <= 4) return bestMatch.string;
   return distances.map((d) => d.variant);
-}
+}

package/src/types/oas3_1.ts

@@ -97,6 +97,13 @@ const Operation: NodeType = {
 
 const Schema: NodeType = {
   properties: {
+    $id: { type: 'string' },
+    id: { type: 'string' },
+    $schema: { type: 'string' },
+    definitions: 'NamedSchemas',
+    $defs: 'NamedSchemas',
+    $vocabulary: { type: 'string' },
+
     externalDocs: 'ExternalDocs',
     discriminator: 'Discriminator',
     myArbitraryKeyword: { type: 'boolean' },