@redocly/openapi-core 1.0.0-beta.100

package/src/typings/openapi.ts

@@ -0,0 +1,298 @@
+export interface Oas3Definition {
+  openapi: string;
+  info?: Oas3Info;
+  servers?: Oas3Server[];
+  paths?: Oas3Paths;
+  components?: Oas3Components;
+  security?: Oas3SecurityRequirement[];
+  tags?: Oas3Tag[];
+  externalDocs?: Oas3ExternalDocs;
+  'x-webhooks'?: Oas3_1Webhooks;
+}
+
+export interface Oas3Info {
+  title: string;
+  version: string;
+
+  description?: string;
+  termsOfService?: string;
+  contact?: Oas3Contact;
+  license?: Oas3License;
+}
+
+export interface Oas3Server {
+  url: string;
+  description?: string;
+  variables?: { [name: string]: Oas3ServerVariable };
+}
+
+export interface Oas3ServerVariable {
+  enum?: string[];
+  default: string;
+  description?: string;
+}
+
+export interface Oas3Paths {
+  [path: string]: Referenced<Oas3PathItem>;
+}
+export interface OasRef {
+  $ref: string;
+}
+
+export type Referenced<T> = OasRef | T;
+
+export interface Oas3PathItem {
+  summary?: string;
+  description?: string;
+  get?: Oas3Operation;
+  put?: Oas3Operation;
+  post?: Oas3Operation;
+  delete?: Oas3Operation;
+  options?: Oas3Operation;
+  head?: Oas3Operation;
+  patch?: Oas3Operation;
+  trace?: Oas3Operation;
+  servers?: Oas3Server[];
+  parameters?: Array<Referenced<Oas3Parameter>>;
+}
+
+export interface Oas3XCodeSample {
+  lang: string;
+  label?: string;
+  source: string;
+}
+
+export interface Oas3Operation {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: Oas3ExternalDocs;
+  operationId?: string;
+  parameters?: Array<Referenced<Oas3Parameter>>;
+  requestBody?: Referenced<Oas3RequestBody>;
+  responses: Oas3Responses;
+  callbacks?: { [name: string]: Referenced<Oas3Callback> };
+  deprecated?: boolean;
+  security?: Oas3SecurityRequirement[];
+  servers?: Oas3Server[];
+  'x-codeSamples'?: Oas3XCodeSample[];
+  'x-code-samples'?: Oas3XCodeSample[]; // deprecated
+  'x-hideTryItPanel'?: boolean;
+}
+
+export interface Oas3Parameter {
+  name: string;
+  in?: Oas3ParameterLocation;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  style?: Oas3ParameterStyle;
+  explode?: boolean;
+  allowReserved?: boolean;
+  schema?: Referenced<Oas3Schema>;
+  example?: any;
+  examples?: { [media: string]: Referenced<Oas3Example> };
+  content?: { [media: string]: Oas3MediaType };
+}
+
+export interface Oas3Example {
+  value: any;
+  summary?: string;
+  description?: string;
+  externalValue?: string;
+}
+
+export interface Oas3Xml {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: string;
+  wrapped?: string;
+}
+
+export interface Oas3Schema {
+  $ref?: string;
+  type?: string;
+  properties?: { [name: string]: Oas3Schema };
+  additionalProperties?: boolean | Oas3Schema;
+  description?: string;
+  default?: any;
+  items?: Oas3Schema;
+  required?: string[];
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  deprecated?: boolean;
+  format?: string;
+  externalDocs?: Oas3ExternalDocs;
+  discriminator?: Oas3Discriminator;
+  nullable?: boolean;
+  oneOf?: Oas3Schema[];
+  anyOf?: Oas3Schema[];
+  allOf?: Oas3Schema[];
+  not?: Oas3Schema;
+
+  title?: string;
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: boolean;
+  minimum?: number;
+  exclusiveMinimum?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxProperties?: number;
+  minProperties?: number;
+  enum?: any[];
+  example?: any;
+
+  xml?: Oas3Xml;
+  'x-tags'?: string[];
+}
+
+export type Oas3_1Schema = Oas3Schema & {
+  type?: string | string[];
+  examples?: any[];
+}
+
+export interface Oas3_1Definition extends Oas3Definition {
+  webhooks?: Oas3_1Webhooks;
+}
+
+export interface Oas3_1Webhooks {
+  [webhook: string]: Referenced<Oas3PathItem>;
+}
+
+export interface Oas3Discriminator {
+  propertyName: string;
+  mapping?: { [name: string]: string };
+  'x-explicitMappingOnly'?: boolean;
+}
+
+export interface Oas3MediaType {
+  schema?: Referenced<Oas3Schema>;
+  example?: any;
+  examples?: { [name: string]: Referenced<Oas3Example> };
+  encoding?: { [field: string]: Oas3Encoding };
+}
+
+export interface Oas3Encoding {
+  contentType: string;
+  headers?: { [name: string]: Referenced<Oas3Header> };
+  style: Oas3ParameterStyle;
+  explode: boolean;
+  allowReserved: boolean;
+}
+
+export type Oas3ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
+export type Oas3ParameterStyle =
+  | 'matrix'
+  | 'label'
+  | 'form'
+  | 'simple'
+  | 'spaceDelimited'
+  | 'pipeDelimited'
+  | 'deepObject';
+
+export interface Oas3RequestBody {
+  description?: string;
+  required?: boolean;
+  content: { [mime: string]: Oas3MediaType };
+}
+
+export interface Oas3Responses {
+  [code: string]: Oas3Response;
+}
+
+export interface Oas3Response {
+  description?: string;
+  headers?: { [name: string]: Referenced<Oas3Header> };
+  content?: { [mime: string]: Oas3MediaType };
+  links?: { [name: string]: Referenced<Oas3Link> };
+}
+
+export interface Oas3Link {
+  $ref?: string;
+}
+
+export type Oas3Header = Omit<Oas3Parameter, 'in' | 'name'>;
+
+export interface Oas3Callback {
+  [name: string]: Oas3PathItem;
+}
+
+export interface Oas3Components {
+  schemas?: { [name: string]: Referenced<Oas3Schema> };
+  responses?: { [name: string]: Referenced<Oas3Response> };
+  parameters?: { [name: string]: Referenced<Oas3Parameter> };
+  examples?: { [name: string]: Referenced<Oas3Example> };
+  requestBodies?: { [name: string]: Referenced<Oas3RequestBody> };
+  headers?: { [name: string]: Referenced<Oas3Header> };
+  securitySchemes?: { [name: string]: Referenced<Oas3SecurityScheme> };
+  links?: { [name: string]: Referenced<Oas3Link> };
+  callbacks?: { [name: string]: Referenced<Oas3Callback> };
+}
+
+export type Oas3ComponentName = keyof Oas3Components;
+
+export interface Oas3SecurityRequirement {
+  [name: string]: string[];
+}
+
+export interface Oas3SecurityScheme {
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+  description?: string;
+  name?: string;
+  in?: 'query' | 'header' | 'cookie';
+  scheme?: string;
+  bearerFormat: string;
+  flows: {
+    implicit?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      authorizationUrl: string;
+    };
+    password?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      tokenUrl: string;
+    };
+    clientCredentials?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      tokenUrl: string;
+    };
+    authorizationCode?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      tokenUrl: string;
+    };
+  };
+  openIdConnectUrl?: string;
+}
+
+export interface Oas3Tag {
+  name: string;
+  description?: string;
+  externalDocs?: Oas3ExternalDocs;
+  'x-displayName'?: string;
+}
+
+export interface Oas3ExternalDocs {
+  description?: string;
+  url: string;
+}
+
+export interface Oas3Contact {
+  name?: string;
+  url?: string;
+  email?: string;
+}
+
+export interface Oas3License {
+  name: string;
+  url?: string;
+}

package/src/typings/swagger.ts

@@ -0,0 +1,236 @@
+import { Referenced } from './openapi';
+import { Schema } from 'js-yaml';
+
+export interface Oas2Definition {
+  swagger: '2.0';
+  info?: Oas2Info;
+  paths?: Oas2Paths;
+
+  basePath?: string;
+  schemes?: string[];
+  consumes?: string[];
+  produces?: string[];
+
+  definitions?: Record<string, Oas2Schema>;
+  responses?: Record<string, Oas2Response>;
+  parameters?: Record<string, Oas2Parameter>;
+  securityDefinitions?: Record<string, Oas2SecurityScheme>;
+  security?: Oas2SecurityRequirement[];
+  tags?: Oas2Tag[];
+  externalDocs?: Oas2ExternalDocs;
+}
+
+export interface Oas2Components {
+  definitions?: { [name: string]: Record<string, Oas2Schema> };
+  securityDefinitions?: { [name: string]: Record<string, Oas2SecurityScheme> };
+  responses?: { [name: string]: Record<string, Oas2Response> };
+  parameters?: { [name: string]: Record<string, Oas2Parameter> };
+}
+
+export interface Oas2Info {
+  title: string;
+  version: string;
+
+  description?: string;
+  termsOfService?: string;
+  contact?: Oas2Contact;
+  license?: Oas2License;
+}
+
+export interface Oas2Paths {
+  [path: string]: Oas2PathItem;
+}
+
+export interface Oas2PathItem {
+  get?: Oas2Operation;
+  put?: Oas2Operation;
+  post?: Oas2Operation;
+  delete?: Oas2Operation;
+  options?: Oas2Operation;
+  head?: Oas2Operation;
+  patch?: Oas2Operation;
+  parameters?: Array<Referenced<Oas2Parameter>>;
+}
+
+export interface Oas2XCodeSample {
+  lang: string;
+  label?: string;
+  source: string;
+}
+
+export interface Oas2Operation {
+  tags?: string[];
+  consumes?: string[];
+  produces?: string[];
+  schemes?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: Oas2ExternalDocs;
+  operationId?: string;
+  parameters?: Array<Referenced<Oas2Parameter>>;
+  responses: Oas2Responses;
+  deprecated?: boolean;
+  security?: Oas2SecurityRequirement[];
+  'x-codeSamples'?: Oas2XCodeSample[];
+  'x-code-samples'?: Oas2XCodeSample[]; // deprecated
+  'x-hideTryItPanel'?: boolean;
+}
+
+export type Oas2Parameter = Oas2BodyParameter | Oas2SimpleParameter;
+
+export interface Oas2BodyParameter {
+  name: string;
+  in: 'body';
+  schema: Oas2Schema;
+
+  description?: string;
+  required?: boolean;
+}
+
+export interface Oas2SimpleParameter {
+  name: string;
+  in: Oas2ParameterLocation;
+  description?: string;
+  required?: boolean;
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'file';
+
+  format?: string;
+  allowEmptyValue?: boolean;
+  items?: Oas2Items;
+  collectionFormat?: 'csv' | 'ssv' | 'tsv' | 'pipes' | 'multi';
+  default?: any;
+  maximum?: number;
+  exclusiveMaximum?: boolean;
+  minimum?: number;
+  exclusiveMinimum?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  enum?: any[];
+  multipleOf?: number;
+}
+
+export interface Oas2Items {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+
+  format?: string;
+  allowEmptyValue?: boolean;
+  items?: Oas2Items;
+  collectionFormat?: 'csv' | 'ssv' | 'tsv' | 'pipes' | 'multi';
+  default?: any;
+  maximum?: number;
+  exclusiveMaximum?: boolean;
+  minimum?: number;
+  exclusiveMinimum?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  enum?: any[];
+  multipleOf?: number;
+}
+
+export interface Oas2Xml {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: string;
+  wrapped?: string;
+}
+
+export interface Oas2Schema {
+  $ref?: string;
+  type?: string;
+  properties?: { [name: string]: Oas2Schema };
+  additionalProperties?: boolean | Oas2Schema;
+  description?: string;
+  default?: any;
+  items?: Oas2Schema;
+  required?: string[];
+  readOnly?: boolean;
+  deprecated?: boolean;
+  format?: string;
+  externalDocs?: Oas2ExternalDocs;
+  discriminator?: string;
+  nullable?: boolean;
+  allOf?: Oas2Schema[];
+
+  title?: string;
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: boolean;
+  minimum?: number;
+  exclusiveMinimum?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxProperties?: number;
+  minProperties?: number;
+  enum?: any[];
+  example?: any;
+
+  xml?: Oas2Xml;
+  'x-tags'?: string[];
+}
+
+export type Oas2ParameterLocation = 'query' | 'header' | 'path' | 'formData';
+
+export interface Oas2Responses {
+  [code: string]: Oas2Response;
+}
+
+export type Oas2Header = Oas2Items & { description?: 'string' };
+
+export interface Oas2Response {
+  description?: string;
+  schema: Referenced<Schema>;
+  examples?: Record<string, any>;
+  headers?: Record<string, Oas2Header>;
+}
+
+export interface Oas2SecurityRequirement {
+  [name: string]: string[];
+}
+
+export interface Oas2SecurityScheme {
+  type: 'basic' | 'apiKey' | 'oauth2';
+  description?: string;
+  name?: string;
+  in?: 'query' | 'header' | 'cookie';
+  scheme?: string;
+  flow: 'implicit' | 'password' | 'application' | 'accessCode';
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  scopes?: Record<string, string>;
+}
+
+export interface Oas2Tag {
+  name: string;
+  description?: string;
+  externalDocs?: Oas2ExternalDocs;
+  'x-displayName'?: string;
+}
+
+export interface Oas2ExternalDocs {
+  description?: string;
+  url: string;
+}
+
+export interface Oas2Contact {
+  name?: string;
+  url?: string;
+  email?: string;
+}
+
+export interface Oas2License {
+  name: string;
+  url?: string;
+}

package/src/utils.ts

@@ -0,0 +1,193 @@
+import * as fs from 'fs';
+import * as minimatch from 'minimatch';
+import fetch from 'node-fetch';
+import * as pluralize from 'pluralize';
+import { parseYaml } from './js-yaml';
+import { UserContext } from './walk';
+import type { HttpResolveConfig } from './config';
+import { env } from "./config";
+
+export { parseYaml, stringifyYaml } from './js-yaml';
+
+export type StackFrame<T> = {
+  prev: StackFrame<T> | null;
+  value: T;
+};
+
+export type Stack<T> = StackFrame<T> | null;
+export type StackNonEmpty<T> = StackFrame<T>;
+export function pushStack<T, P extends Stack<T> = Stack<T>>(head: P, value: T) {
+  return { prev: head, value };
+}
+
+export function popStack<T, P extends Stack<T>>(head: P) {
+  return head?.prev ?? null;
+}
+
+export type BundleOutputFormat = 'json' | 'yml' | 'yaml';
+
+export async function loadYaml(filename: string) {
+  const contents = await fs.promises.readFile(filename, 'utf-8');
+  return parseYaml(contents);
+}
+
+export function notUndefined<T>(x: T | undefined): x is T {
+  return x !== undefined;
+}
+
+export function isPlainObject(value: any): value is object {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isEmptyObject(value: any): value is object {
+  return isPlainObject(value) && Object.keys(value).length === 0;
+}
+
+export function isEmptyArray(value: any) {
+  return Array.isArray(value) && value.length === 0;
+}
+
+export async function readFileFromUrl(url: string, config: HttpResolveConfig) {
+  const headers: Record<string, string> = {};
+  for (const header of config.headers) {
+    if (match(url, header.matches)) {
+      headers[header.name] =
+        header.envVariable !== undefined ? env[header.envVariable] || '' : header.value;
+    }
+  }
+
+  const req = await (config.customFetch || fetch)(url, {
+    headers: headers,
+  });
+
+  if (!req.ok) {
+    throw new Error(`Failed to load ${url}: ${req.status} ${req.statusText}`);
+  }
+
+  return { body: await req.text(), mimeType: req.headers.get('content-type') };
+}
+
+function match(url: string, pattern: string) {
+  if (!pattern.match(/^https?:\/\//)) {
+    // if pattern doesn't specify protocol directly, do not match against it
+    url = url.replace(/^https?:\/\//, '');
+  }
+  return minimatch(url, pattern);
+}
+
+export function pickObjectProps<T extends Record<string, unknown>>(
+  object: T,
+  keys: Array<string>,
+): T {
+  return Object.fromEntries(
+    keys.filter((key: string) => key in object).map((key: string) => [key, object[key]]),
+  ) as T;
+}
+
+export function omitObjectProps<T extends Record<string, unknown>>(
+  object: T,
+  keys: Array<string>,
+): T {
+  return Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key))) as T;
+}
+
+export function splitCamelCaseIntoWords(str: string) {
+  const camel = str
+    .split(/(?:[-._])|([A-Z][a-z]+)/)
+    .filter(Boolean)
+    .map((item) => item.toLocaleLowerCase());
+  const caps = str
+    .split(/([A-Z]{2,})/)
+    .filter((e: string) => e && e === e.toUpperCase())
+    .map((item) => item.toLocaleLowerCase());
+  return new Set([...camel, ...caps]);
+}
+
+export function validateMimeType(
+  { type, value }: any,
+  { report, location }: UserContext,
+  allowedValues: string[],
+) {
+  const ruleType = type === 'consumes' ? 'request' : 'response';
+  if (!allowedValues)
+    throw new Error(`Parameter "allowedValues" is not provided for "${ruleType}-mime-type" rule`);
+  if (!value[type]) return;
+
+  for (const mime of value[type]) {
+    if (!allowedValues.includes(mime)) {
+      report({
+        message: `Mime type "${mime}" is not allowed`,
+        location: location.child(value[type].indexOf(mime)).key(),
+      });
+    }
+  }
+}
+
+export function validateMimeTypeOAS3(
+  { type, value }: any,
+  { report, location }: UserContext,
+  allowedValues: string[],
+) {
+  const ruleType = type === 'consumes' ? 'request' : 'response';
+  if (!allowedValues)
+    throw new Error(`Parameter "allowedValues" is not provided for "${ruleType}-mime-type" rule`);
+  if (!value.content) return;
+
+  for (const mime of Object.keys(value.content)) {
+    if (!allowedValues.includes(mime)) {
+      report({
+        message: `Mime type "${mime}" is not allowed`,
+        location: location.child('content').child(mime).key(),
+      });
+    }
+  }
+}
+
+export function isSingular(path: string) {
+  return pluralize.isSingular(path);
+}
+
+export function readFileAsStringSync(filePath: string) {
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+export function isPathParameter(pathSegment: string) {
+  return pathSegment.startsWith('{') && pathSegment.endsWith('}');
+}
+
+
+/**
+ * Convert Windows backslash paths to slash paths: foo\\bar ➔ foo/bar
+ */
+ export function slash(path: string): string {
+  const isExtendedLengthPath = /^\\\\\?\\/.test(path)
+  if (isExtendedLengthPath) {
+    return path
+  }
+
+  return path.replace(/\\/g, '/');
+}
+
+export function isNotEmptyObject(obj: any) {
+  return !!obj && Object.keys(obj).length > 0;
+}
+
+// TODO: use it everywhere
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+export function isNotString<T>(value: string | T): value is T {
+  return !isString(value);
+}
+
+export function assignExisting<T>(target: Record<string, T>, obj: Record<string, T>) {
+  for (let k of Object.keys(obj)) {
+    if (target.hasOwnProperty(k)) {
+      target[k] = obj[k];
+    }
+  }
+}
+
+export const getMatchingStatusCodeRange = (code: number | string): string =>
+  `${code}`.replace(/^(\d)\d\d$/, (_, firstDigit) => `${firstDigit}XX`);