Faster OpenAPI spec validation (#2871)

Author: gregberge

.changeset/early-cameras-battle.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/openapi-parser': patch
+'gitbook': patch
+---
+
+Implement a trusted mode to speed up OpenAPI spec validation

packages/gitbook/src/lib/openapi/fetch.ts

@@ -82,7 +82,13 @@ const fetchFilesystem = cache({
  }
 
  const text = await response.text();
- const filesystem = await parseOpenAPI({ value: text, rootURL: url });
+ const filesystem = await parseOpenAPI({
+ value: text,
+ rootURL: url,
+ // If we fetch the OpenAPI specification
+ // it's the legacy system, it means the spec can be trusted here.
+ trust: true,
+ });
  const richFilesystem = await enrichFilesystem(filesystem);
  return {
  // Cache for 4 hours

packages/openapi-parser/src/parse.ts

@@ -3,12 +3,7 @@ import { OpenAPIParseError } from './error';
 import { convertOpenAPIV2ToOpenAPIV3 } from './v2';
 import { parseOpenAPIV3 } from './v3';
 
-/**
- * Parse a raw string into an OpenAPI document.
- * It will also convert Swagger 2.0 to OpenAPI 3.0.
- * It can throw an `OpenAPIParseError` if the document is invalid.
- */
-export async function parseOpenAPI(input: {
+export interface ParseOpenAPIInput {
  /**
  * The API definition to parse.
  */
@@ -17,7 +12,18 @@ export async function parseOpenAPI(input: {
  * The root URL of the specified OpenAPI document.
  */
  rootURL: string | null;
-}) {
+ /**
+ * Trust the input. This will skip advanced validation.
+ */
+ trust?: boolean;
+}
+
+/**
+ * Parse a raw string into an OpenAPI document.
+ * It will also convert Swagger 2.0 to OpenAPI 3.0.
+ * It can throw an `OpenAPIParseError` if the document is invalid.
+ */
+export async function parseOpenAPI(input: ParseOpenAPIInput) {
  try {
  return await parseOpenAPIV3(input);
  } catch (error) {

packages/openapi-parser/src/scalar-plugins/fetchURLs.ts

@@ -43,7 +43,7 @@ export const fetchURLs: (customConfiguration: {
  return true;
  },
  async get(value?: any) {
- // Limit ht enumber of requests
+ // Limit the number of requests
  if (configuration?.limit !== false && numberOfRequests >= configuration?.limit) {
  console.warn(
  `[fetchUrls] Maximum number of requests reeached (${configuration?.limit}), skipping request`,

packages/openapi-parser/src/v2.ts

@@ -3,22 +3,15 @@ import swagger2openapi, { type ConvertOutputOptions } from 'swagger2openapi';
 
 import { OpenAPIParseError } from './error';
 import { parseOpenAPIV3 } from './v3';
-import type { AnyApiDefinitionFormat } from '@scalar/openapi-parser';
 import type { Filesystem, OpenAPIV3xDocument } from './types';
+import type { ParseOpenAPIInput } from './parse';
 
 /**
  * Convert a Swagger 2.0 schema to an OpenAPI 3.0 schema.
  */
-export async function convertOpenAPIV2ToOpenAPIV3(input: {
- /**
- * The API definition to parse.
- */
- value: AnyApiDefinitionFormat;
- /**
- * The root URL of the specified OpenAPI document.
- */
- rootURL: string | null;
-}): Promise<Filesystem<OpenAPIV3xDocument>> {
+export async function convertOpenAPIV2ToOpenAPIV3(
+ input: ParseOpenAPIInput,
+): Promise<Filesystem<OpenAPIV3xDocument>> {
  const { value, rootURL } = input;
  // In this case we want the raw value to be able to convert it.
  const schema = typeof value === 'string' ? rawParseOpenAPI({ value, rootURL }) : value;
@@ -35,7 +28,7 @@ export async function convertOpenAPIV2ToOpenAPIV3(input: {
  patch: true,
  })) as ConvertOutputOptions;
 
- return parseOpenAPIV3({ rootURL, value: convertResult.openapi });
+ return parseOpenAPIV3({ ...input, rootURL, value: convertResult.openapi });
  } catch (error) {
  if (error instanceof Error && error.name === 'S2OError') {
  throw new OpenAPIParseError('Failed to convert Swagger 2.0 to OpenAPI 3.0', {

packages/openapi-parser/src/v3.ts

@@ -1,23 +1,33 @@
-import { type AnyApiDefinitionFormat, validate } from '@scalar/openapi-parser';
+import { validate } from '@scalar/openapi-parser';
 import { OpenAPIParseError } from './error';
 import { createFileSystem } from './filesystem';
 import type { Filesystem, OpenAPIV3xDocument } from './types';
+import type { ParseOpenAPIInput } from './parse';
 
 /**
  * Parse a raw string into an OpenAPI document.
  * It will also convert Swagger 2.0 to OpenAPI 3.0.
  * It can throw an `OpenAPIFetchError` if the document is invalid.
  */
-export async function parseOpenAPIV3(input: {
- /**
- * The API definition to parse.
- */
- value: AnyApiDefinitionFormat;
- /**
- * The root URL of the specified OpenAPI document.
- */
- rootURL: string | null;
-}): Promise<Filesystem<OpenAPIV3xDocument>> {
+export async function parseOpenAPIV3(
+ input: ParseOpenAPIInput,
+): Promise<Filesystem<OpenAPIV3xDocument>> {
+ const { value, rootURL, trust } = input;
+ const specification = trust
+ ? trustedValidate({ value, rootURL })
+ : await untrustedValidate({ value, rootURL });
+
+ const filesystem = await createFileSystem({ value: specification, rootURL });
+
+ return filesystem;
+}
+
+type ValidateOpenAPIV3Input = Pick<ParseOpenAPIInput, 'value' | 'rootURL'>;
+
+/**
+ * Validate an untrusted OpenAPI v3 document.
+ */
+async function untrustedValidate(input: ValidateOpenAPIV3Input) {
  const { value, rootURL } = input;
  const result = await validate(value);
 
@@ -36,7 +46,36 @@ export async function parseOpenAPIV3(input: {
  });
  }
 
- const filesystem = await createFileSystem({ value: result.specification, rootURL });
+ return result.specification;
+}
 
- return filesystem;
+/**
+ * Validate a trusted OpenAPI v3 document.
+ * It assumes the specification is already a valid specification.
+ * It's faster than `untrustedValidate`.
+ */
+function trustedValidate(input: ValidateOpenAPIV3Input) {
+ const { value, rootURL } = input;
+ const result = (() => {
+ if (typeof value === 'string') {
+ try {
+ return JSON.parse(value);
+ } catch (error) {
+ throw new OpenAPIParseError('Invalid JSON', {
+ code: 'invalid',
+ rootURL,
+ });
+ }
+ }
+ return value;
+ })();
+
+ if ('swagger' in result && result.swagger) {
+ throw new OpenAPIParseError('Only OpenAPI v3 is supported', {
+ code: 'parse-v2-in-v3',
+ rootURL,
+ });
+ }
+
+ return result;
 }