@redocly/openapi-core 1.0.0 → 1.0.1

package/src/types/index.ts

@@ -0,0 +1,149 @@
+export type ScalarSchema = {
+  name?: never;
+  type?: 'string' | 'boolean' | 'number' | 'integer' | 'object' | 'array';
+  items?: ScalarSchema;
+  enum?: string[];
+  isExample?: boolean;
+  directResolveAs?: string;
+  minimum?: number;
+};
+
+export type NormalizedScalarSchema = {
+  name?: never;
+  type?: 'string' | 'boolean' | 'number' | 'integer' | 'object' | 'array';
+  items?: ScalarSchema;
+  enum?: string[];
+  directResolveAs?: NormalizedNodeType;
+  resolvable: boolean;
+  minimum?: number;
+};
+
+export type NodeType = {
+  properties: Record<string, PropType | ResolveTypeFn>;
+  additionalProperties?: PropType | ResolveTypeFn;
+  items?: string;
+  required?: string[] | ((value: any, key: string | number | undefined) => string[]);
+  requiredOneOf?: string[];
+  allowed?: (value: any) => string[] | undefined;
+  extensionsPrefix?: string;
+};
+type PropType = string | NodeType | ScalarSchema | undefined | null;
+type ResolveTypeFn = (value: any, key: string) => string | PropType;
+
+export type NormalizedNodeType = {
+  name: string;
+  properties: Record<string, NormalizedPropType | NormalizedResolveTypeFn>;
+  additionalProperties?: NormalizedPropType | NormalizedResolveTypeFn;
+  items?: NormalizedNodeType;
+  required?: string[] | ((value: any, key: string | number | undefined) => string[]);
+  requiredOneOf?: string[];
+  allowed?: (value: any) => string[] | undefined;
+  extensionsPrefix?: string;
+};
+
+type NormalizedPropType = NormalizedNodeType | NormalizedScalarSchema | undefined | null;
+type NormalizedResolveTypeFn = (
+  value: any,
+  key: string
+) => NormalizedNodeType | NormalizedScalarSchema | undefined | null;
+
+export function listOf(typeName: string) {
+  return {
+    name: `${typeName}List`,
+    properties: {},
+    items: typeName,
+  };
+}
+
+export function mapOf(typeName: string) {
+  return {
+    name: `${typeName}Map`,
+    properties: {},
+    additionalProperties: () => typeName,
+  };
+}
+
+export const SpecExtension: NormalizedNodeType = {
+  name: 'SpecExtension',
+  properties: {},
+  // skip validation of additional properties for unknown extensions
+  additionalProperties: { resolvable: true },
+};
+
+export function normalizeTypes(
+  types: Record<string, NodeType>,
+  options: { doNotResolveExamples?: boolean } = {}
+): Record<string, NormalizedNodeType> {
+  const normalizedTypes: Record<string, NormalizedNodeType> = {};
+
+  for (const typeName of Object.keys(types)) {
+    normalizedTypes[typeName] = {
+      ...types[typeName],
+      name: typeName,
+    } as NormalizedNodeType;
+  }
+
+  for (const type of Object.values(normalizedTypes)) {
+    normalizeType(type);
+  }
+
+  // all type trees have a SpecExtension type by default
+  normalizedTypes['SpecExtension'] = SpecExtension;
+
+  return normalizedTypes;
+
+  function normalizeType(type: NormalizedNodeType) {
+    if (type.additionalProperties) {
+      type.additionalProperties = resolveType(type.additionalProperties);
+    }
+    if (type.items) {
+      type.items = resolveType(type.items);
+    }
+
+    if (type.properties) {
+      const mappedProps: Record<string, any> = {};
+      for (const [propName, prop] of Object.entries(type.properties)) {
+        mappedProps[propName] = resolveType(prop);
+
+        if (options.doNotResolveExamples && prop && (prop as ScalarSchema).isExample) {
+          mappedProps[propName] = {
+            ...(prop as object),
+            resolvable: false,
+          };
+        }
+      }
+      type.properties = mappedProps;
+    }
+  }
+
+  // typings are painful here...
+  function resolveType(type?: any): any {
+    if (typeof type === 'string') {
+      if (!normalizedTypes[type]) {
+        throw new Error(`Unknown type name found: ${type}`);
+      }
+      return normalizedTypes[type];
+    } else if (typeof type === 'function') {
+      return (value: any, key: string) => {
+        return resolveType(type(value, key));
+      };
+    } else if (type && type.name) {
+      type = { ...type };
+      normalizeType(type);
+      return type;
+    } else if (type && type.directResolveAs) {
+      return {
+        ...type,
+        directResolveAs: resolveType(type.directResolveAs),
+      };
+    } else {
+      return type;
+    }
+  }
+}
+
+export function isNamedType(
+  t: NormalizedNodeType | NormalizedScalarSchema | null | undefined
+): t is NormalizedNodeType {
+  return typeof t?.name === 'string';
+}

package/src/types/oas2.ts

@@ -0,0 +1,478 @@
+import { NodeType, listOf, mapOf } from '.';
+
+const responseCodeRegexp = /^[0-9][0-9Xx]{2}$/;
+
+const Root: NodeType = {
+  properties: {
+    swagger: { type: 'string' },
+    info: 'Info',
+    host: { type: 'string' },
+    basePath: { type: 'string' },
+    schemes: { type: 'array', items: { type: 'string' } },
+    consumes: { type: 'array', items: { type: 'string' } },
+    produces: { type: 'array', items: { type: 'string' } },
+    paths: 'Paths',
+    definitions: 'NamedSchemas',
+    parameters: 'NamedParameters',
+    responses: 'NamedResponses',
+    securityDefinitions: 'NamedSecuritySchemes',
+    security: 'SecurityRequirementList',
+    tags: 'TagList',
+    externalDocs: 'ExternalDocs',
+    'x-servers': 'XServerList',
+    'x-tagGroups': 'TagGroups',
+    'x-ignoredHeaderParameters': { type: 'array', items: { type: 'string' } },
+  },
+  required: ['swagger', 'paths', 'info'],
+  extensionsPrefix: 'x-',
+};
+
+const Info: NodeType = {
+  properties: {
+    title: { type: 'string' },
+    description: { type: 'string' },
+    termsOfService: { type: 'string' },
+    contact: 'Contact',
+    license: 'License',
+    version: { type: 'string' },
+    'x-logo': 'Logo',
+  },
+  required: ['title', 'version'],
+  extensionsPrefix: 'x-',
+};
+
+const Logo: NodeType = {
+  properties: {
+    url: { type: 'string' },
+    altText: { type: 'string' },
+    backgroundColor: { type: 'string' },
+    href: { type: 'string' },
+  },
+  extensionsPrefix: 'x-',
+};
+
+const Contact: NodeType = {
+  properties: {
+    name: { type: 'string' },
+    url: { type: 'string' },
+    email: { type: 'string' },
+  },
+  extensionsPrefix: 'x-',
+};
+
+const License: NodeType = {
+  properties: {
+    name: { type: 'string' },
+    url: { type: 'string' },
+  },
+  required: ['name'],
+  extensionsPrefix: 'x-',
+};
+
+const Paths: NodeType = {
+  properties: {},
+  additionalProperties: (_value: any, key: string) =>
+    key.startsWith('/') ? 'PathItem' : undefined,
+};
+
+const PathItem: NodeType = {
+  properties: {
+    $ref: { type: 'string' }, // TODO: verify special $ref handling for Path Item
+    parameters: 'ParameterList',
+
+    get: 'Operation',
+    put: 'Operation',
+    post: 'Operation',
+    delete: 'Operation',
+    options: 'Operation',
+    head: 'Operation',
+    patch: 'Operation',
+  },
+  extensionsPrefix: 'x-',
+};
+
+const Operation: NodeType = {
+  properties: {
+    tags: { type: 'array', items: { type: 'string' } },
+    summary: { type: 'string' },
+    description: { type: 'string' },
+    externalDocs: 'ExternalDocs',
+    operationId: { type: 'string' },
+    consumes: { type: 'array', items: { type: 'string' } },
+    produces: { type: 'array', items: { type: 'string' } },
+    parameters: 'ParameterList',
+    responses: 'Responses',
+    schemes: { type: 'array', items: { type: 'string' } },
+    deprecated: { type: 'boolean' },
+    security: 'SecurityRequirementList',
+    'x-codeSamples': 'XCodeSampleList',
+    'x-code-samples': 'XCodeSampleList', // deprecated
+    'x-hideTryItPanel': { type: 'boolean' },
+  },
+  required: ['responses'],
+  extensionsPrefix: 'x-',
+};
+
+const XCodeSample: NodeType = {
+  properties: {
+    lang: { type: 'string' },
+    label: { type: 'string' },
+    source: { type: 'string' },
+  },
+};
+
+const XServer: NodeType = {
+  properties: {
+    url: { type: 'string' },
+    description: { type: 'string' },
+  },
+  required: ['url'],
+};
+
+const ExternalDocs: NodeType = {
+  properties: {
+    description: { type: 'string' },
+    url: { type: 'string' },
+  },
+  required: ['url'],
+  extensionsPrefix: 'x-',
+};
+
+const Parameter: NodeType = {
+  properties: {
+    name: { type: 'string' },
+    in: { type: 'string', enum: ['query', 'header', 'path', 'formData', 'body'] },
+    description: { type: 'string' },
+    required: { type: 'boolean' },
+    schema: 'Schema',
+    type: { type: 'string', enum: ['string', 'number', 'integer', 'boolean', 'array', 'file'] },
+    format: { type: 'string' },
+    allowEmptyValue: { type: 'boolean' },
+    items: 'ParameterItems',
+    collectionFormat: { type: 'string', enum: ['csv', 'ssv', 'tsv', 'pipes', 'multi'] },
+    default: null,
+    maximum: { type: 'integer' },
+    exclusiveMaximum: { type: 'boolean' },
+    minimum: { type: 'integer' },
+    exclusiveMinimum: { type: 'boolean' },
+    maxLength: { type: 'integer' },
+    minLength: { type: 'integer' },
+    pattern: { type: 'string' },
+    maxItems: { type: 'integer' },
+    minItems: { type: 'integer' },
+    uniqueItems: { type: 'boolean' },
+    enum: { type: 'array' },
+    multipleOf: { type: 'number' },
+    'x-example': 'Example',
+    'x-examples': 'ExamplesMap',
+  },
+  required(value) {
+    if (!value || !value.in) {
+      return ['name', 'in'];
+    }
+    if (value.in === 'body') {
+      return ['name', 'in', 'schema'];
+    } else {
+      if (value.type === 'array') {
+        return ['name', 'in', 'type', 'items'];
+      } else {
+        return ['name', 'in', 'type'];
+      }
+    }
+  },
+  extensionsPrefix: 'x-',
+};
+
+const ParameterItems: NodeType = {
+  properties: {
+    type: { type: 'string', enum: ['string', 'number', 'integer', 'boolean', 'array'] },
+    format: { type: 'string' },
+    items: 'ParameterItems',
+    collectionFormat: { type: 'string', enum: ['csv', 'ssv', 'tsv', 'pipes', 'multi'] },
+    default: null,
+    maximum: { type: 'integer' },
+    exclusiveMaximum: { type: 'boolean' },
+    minimum: { type: 'integer' },
+    exclusiveMinimum: { type: 'boolean' },
+    maxLength: { type: 'integer' },
+    minLength: { type: 'integer' },
+    pattern: { type: 'string' },
+    maxItems: { type: 'integer' },
+    minItems: { type: 'integer' },
+    uniqueItems: { type: 'boolean' },
+    enum: { type: 'array' },
+    multipleOf: { type: 'number' },
+  },
+  required(value) {
+    if (value && value.type === 'array') {
+      return ['type', 'items'];
+    } else {
+      return ['type'];
+    }
+  },
+  extensionsPrefix: 'x-',
+};
+
+const Responses: NodeType = {
+  properties: {
+    default: 'Response',
+  },
+  additionalProperties: (_v: any, key: string) =>
+    responseCodeRegexp.test(key) ? 'Response' : undefined,
+};
+
+const Response: NodeType = {
+  properties: {
+    description: { type: 'string' },
+    schema: 'Schema',
+    headers: mapOf('Header'),
+    examples: 'Examples',
+    'x-summary': { type: 'string' },
+  },
+  required: ['description'],
+  extensionsPrefix: 'x-',
+};
+
+const Examples: NodeType = {
+  properties: {},
+  additionalProperties: { isExample: true },
+};
+
+const Header: NodeType = {
+  properties: {
+    description: { type: 'string' },
+    type: { type: 'string', enum: ['string', 'number', 'integer', 'boolean', 'array'] },
+    format: { type: 'string' },
+    items: 'ParameterItems',
+    collectionFormat: { type: 'string', enum: ['csv', 'ssv', 'tsv', 'pipes', 'multi'] },
+    default: null,
+    maximum: { type: 'integer' },
+    exclusiveMaximum: { type: 'boolean' },
+    minimum: { type: 'integer' },
+    exclusiveMinimum: { type: 'boolean' },
+    maxLength: { type: 'integer' },
+    minLength: { type: 'integer' },
+    pattern: { type: 'string' },
+    maxItems: { type: 'integer' },
+    minItems: { type: 'integer' },
+    uniqueItems: { type: 'boolean' },
+    enum: { type: 'array' },
+    multipleOf: { type: 'number' },
+  },
+  required(value) {
+    if (value && value.type === 'array') {
+      return ['type', 'items'];
+    } else {
+      return ['type'];
+    }
+  },
+  extensionsPrefix: 'x-',
+};
+
+const Tag: NodeType = {
+  properties: {
+    name: { type: 'string' },
+    description: { type: 'string' },
+    externalDocs: 'ExternalDocs',
+    'x-traitTag': { type: 'boolean' },
+    'x-displayName': { type: 'string' },
+  },
+  required: ['name'],
+  extensionsPrefix: 'x-',
+};
+
+const TagGroup: NodeType = {
+  properties: {
+    name: { type: 'string' },
+    tags: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+const Schema: NodeType = {
+  properties: {
+    format: { type: 'string' },
+    title: { type: 'string' },
+    description: { type: 'string' },
+    default: null,
+    multipleOf: { type: 'number' },
+    maximum: { type: 'number' },
+    minimum: { type: 'number' },
+    exclusiveMaximum: { type: 'boolean' },
+    exclusiveMinimum: { type: 'boolean' },
+    maxLength: { type: 'number' },
+    minLength: { type: 'number' },
+    pattern: { type: 'string' },
+    maxItems: { type: 'number' },
+    minItems: { type: 'number' },
+    uniqueItems: { type: 'boolean' },
+    maxProperties: { type: 'number' },
+    minProperties: { type: 'number' },
+    required: { type: 'array', items: { type: 'string' } },
+    enum: { type: 'array' },
+    type: {
+      type: 'string',
+      enum: ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'],
+    },
+    items: (value: any) => {
+      if (Array.isArray(value)) {
+        return listOf('Schema');
+      } else {
+        return 'Schema';
+      }
+    },
+    allOf: listOf('Schema'),
+    properties: 'SchemaProperties',
+    additionalProperties: (value: any) => {
+      if (typeof value === 'boolean') {
+        return { type: 'boolean' };
+      } else {
+        return 'Schema';
+      }
+    },
+    discriminator: { type: 'string' },
+    readOnly: { type: 'boolean' },
+    xml: 'Xml',
+    externalDocs: 'ExternalDocs',
+    example: { isExample: true },
+    'x-tags': { type: 'array', items: { type: 'string' } },
+    'x-nullable': { type: 'boolean' },
+    'x-extendedDiscriminator': { type: 'string' },
+    'x-additionalPropertiesName': { type: 'string' },
+    'x-explicitMappingOnly': { type: 'boolean' },
+    'x-enumDescriptions': 'EnumDescriptions',
+  },
+  extensionsPrefix: 'x-',
+};
+
+const EnumDescriptions: NodeType = {
+  properties: {},
+  additionalProperties: { type: 'string' },
+};
+
+const SchemaProperties: NodeType = {
+  properties: {},
+  additionalProperties: 'Schema',
+};
+
+const Xml: NodeType = {
+  properties: {
+    name: { type: 'string' },
+    namespace: { type: 'string' },
+    prefix: { type: 'string' },
+    attribute: { type: 'boolean' },
+    wrapped: { type: 'boolean' },
+  },
+  extensionsPrefix: 'x-',
+};
+
+const SecurityScheme: NodeType = {
+  properties: {
+    type: { enum: ['basic', 'apiKey', 'oauth2'] },
+    description: { type: 'string' },
+    name: { type: 'string' },
+    in: { type: 'string', enum: ['query', 'header'] },
+    flow: { enum: ['implicit', 'password', 'application', 'accessCode'] },
+    authorizationUrl: { type: 'string' },
+    tokenUrl: { type: 'string' },
+    scopes: { type: 'object', additionalProperties: { type: 'string' } },
+    'x-defaultClientId': { type: 'string' },
+  },
+  required(value) {
+    switch (value?.type) {
+      case 'apiKey':
+        return ['type', 'name', 'in'];
+      case 'oauth2':
+        switch (value?.flow) {
+          case 'implicit':
+            return ['type', 'flow', 'authorizationUrl', 'scopes'];
+          case 'accessCode':
+            return ['type', 'flow', 'authorizationUrl', 'tokenUrl', 'scopes'];
+          case 'application':
+          case 'password':
+            return ['type', 'flow', 'tokenUrl', 'scopes'];
+          default:
+            return ['type', 'flow', 'scopes'];
+        }
+      default:
+        return ['type'];
+    }
+  },
+  allowed(value) {
+    switch (value?.type) {
+      case 'basic':
+        return ['type', 'description'];
+      case 'apiKey':
+        return ['type', 'name', 'in', 'description'];
+      case 'oauth2':
+        switch (value?.flow) {
+          case 'implicit':
+            return ['type', 'flow', 'authorizationUrl', 'description', 'scopes'];
+          case 'accessCode':
+            return ['type', 'flow', 'authorizationUrl', 'tokenUrl', 'description', 'scopes'];
+          case 'application':
+          case 'password':
+            return ['type', 'flow', 'tokenUrl', 'description', 'scopes'];
+          default:
+            return ['type', 'flow', 'tokenUrl', 'authorizationUrl', 'description', 'scopes'];
+        }
+      default:
+        return ['type', 'description'];
+    }
+  },
+  extensionsPrefix: 'x-',
+};
+
+const SecurityRequirement: NodeType = {
+  properties: {},
+  additionalProperties: { type: 'array', items: { type: 'string' } },
+};
+
+const Example: NodeType = {
+  properties: {
+    value: { isExample: true },
+    summary: { type: 'string' },
+    description: { type: 'string' },
+    externalValue: { type: 'string' },
+  },
+  extensionsPrefix: 'x-',
+};
+
+export const Oas2Types: Record<string, NodeType> = {
+  Root,
+  Tag,
+  TagList: listOf('Tag'),
+  TagGroups: listOf('TagGroup'),
+  TagGroup,
+  ExternalDocs,
+  Example,
+  ExamplesMap: mapOf('Example'),
+  EnumDescriptions,
+  SecurityRequirement,
+  SecurityRequirementList: listOf('SecurityRequirement'),
+  Info,
+  Contact,
+  License,
+  Logo,
+  Paths,
+  PathItem,
+  Parameter,
+  ParameterItems,
+  ParameterList: listOf('Parameter'),
+  Operation,
+  Examples,
+  Header,
+  Responses,
+  Response,
+  Schema,
+  Xml,
+  SchemaProperties,
+  NamedSchemas: mapOf('Schema'),
+  NamedResponses: mapOf('Response'),
+  NamedParameters: mapOf('Parameter'),
+  NamedSecuritySchemes: mapOf('SecurityScheme'),
+  SecurityScheme,
+  XCodeSample,
+  XCodeSampleList: listOf('XCodeSample'),
+  XServerList: listOf('XServer'),
+  XServer,
+};