From 29dd592f38a938b5247ccccf1846f85baa1f8cd4 Mon Sep 17 00:00:00 2001 From: Anders Kaseorg Date: Thu, 4 Sep 2025 14:34:46 -0700 Subject: [PATCH] types: Add declarations for openapi-examples-validator. Signed-off-by: Anders Kaseorg --- .codespellignore | 1 + .../application-error.d.ts | 60 ++++++++ .../openapi-examples-validator/index.d.ts | 137 ++++++++++++++++++ 3 files changed, 198 insertions(+) create mode 100644 web/src/types/openapi-examples-validator/application-error.d.ts create mode 100644 web/src/types/openapi-examples-validator/index.d.ts diff --git a/.codespellignore b/.codespellignore index 64d0052669..14825cb260 100644 --- a/.codespellignore +++ b/.codespellignore @@ -30,3 +30,4 @@ assertIn thirdparty asend COO +statics diff --git a/web/src/types/openapi-examples-validator/application-error.d.ts b/web/src/types/openapi-examples-validator/application-error.d.ts new file mode 100644 index 0000000000..10e482868d --- /dev/null +++ b/web/src/types/openapi-examples-validator/application-error.d.ts @@ -0,0 +1,60 @@ +export enum ErrorType { + jsENOENT = "ENOENT", + jsonPathNotFound = "JsonPathNotFound", + errorAndErrorsMutuallyExclusive = "ErrorErrorsMutuallyExclusive", + parseError = "ParseError", + validation = "Validation", +} + +export type ApplicationErrorOptions = { + instancePath?: string; + examplePath?: string; + exampleFilePath?: string; + keyword?: string; + message?: string; + mapFilePath?: string; + params?: { + path?: string; + missingProperty?: string; + type?: string; + }; + schemaPath?: string; +}; + +/** + * Unified application-error + */ +export class ApplicationError { + /** + * Factory-function, which is able to consume validation-errors and + * JS-errors. If a validation error is passed, all properties will be + * adopted. + * + * @param err - Javascript-, validation- or custom-error, to create the + * application-error from + * @returns Unified application-error instance + */ + static create(err: Error): ApplicationError; + + /** + * Constructor + * + * @param type - Type of error (see statics) + * @param options - Optional properties + */ + constructor(type: ErrorType, options?: ApplicationErrorOptions); + + type: ErrorType; + instancePath?: string; + examplePath?: string; + exampleFilePath?: string; + keyword?: string; + message?: string; + mapFilePath?: string; + params?: { + path?: string; + missingProperty?: string; + type?: string; + }; + schemaPath?: string; +} diff --git a/web/src/types/openapi-examples-validator/index.d.ts b/web/src/types/openapi-examples-validator/index.d.ts new file mode 100644 index 0000000000..974307b504 --- /dev/null +++ b/web/src/types/openapi-examples-validator/index.d.ts @@ -0,0 +1,137 @@ +import type {ApplicationError} from "./application-error.d.ts"; + +declare namespace OpenApiExamplesValidator { + export type ValidationStatistics = { + schemasWithExamples: number; + examplesTotal: number; + examplesWithoutSchema: number; + matchingFilePathsMapping?: number | undefined; + }; + + export type ValidationResponse = { + valid: boolean; + statistics: ValidationStatistics; + errors: ApplicationError[]; + }; + + /** + * Validates OpenAPI-spec with embedded examples. + * + * @param openapiSpec - OpenAPI-spec + */ + export function validateExamples( + openapiSpec: object, + options?: { + /** + * Don't allow properties that are not defined in the schema + */ + noAdditionalProperties?: boolean | undefined; + /** + * Make all properties required + */ + allPropertiesRequired?: boolean | undefined; + /** + * List of datatype formats that shall be ignored (to prevent + * "unsupported format" errors). If an Array with only one string is + * provided where the formats are separated with `\n`, the entries will + * be expanded to a new array containing all entries. + */ + ignoreFormats?: string[] | undefined; + }, + ): Promise; + // eslint-disable-next-line unicorn/no-named-default + export {validateExamples as default}; + + /** + * Validates OpenAPI-spec with embedded examples. + * + * @param filePath - File-path to the OpenAPI-spec + */ + export function validateFile( + filePath: string, + options?: { + /** + * Don't allow properties that are not defined in the schema + */ + noAdditionalProperties?: boolean | undefined; + /** + * Make all properties required + */ + allPropertiesRequired?: boolean | undefined; + /** + * List of datatype formats that shall be ignored (to prevent + * "unsupported format" errors). If an Array with only one string is + * provided where the formats are separated with `\n`, the entries will + * be expanded to a new array containing all entries. + */ + ignoreFormats?: string[] | undefined; + }, + ): Promise; + + /** + * Validates examples by mapping-files. + * + * @param filePathSchema - File-path to the OpenAPI-spec + * @param globMapExternalExamples - File-path (globs are supported) to the + * mapping-file containing JSON-paths to schemas as key and a single file-path + * or Array of file-paths to external examples + */ + export function validateExamplesByMap( + filePathSchema: string, + globMapExternalExamples: string, + options?: { + /** + * Change working directory for resolving the example-paths (relative to + * the mapping-file) + */ + cwdToMappingFile?: boolean | undefined; + /** + * Don't allow properties that are not defined in the schema + */ + noAdditionalProperties?: boolean | undefined; + /** + * Make all properties required + */ + allPropertiesRequired?: boolean | undefined; + /** + * List of datatype formats that shall be ignored (to prevent + * "unsupported format" errors). If an Array with only one string is + * provided where the formats are separated with `\n`, the entries will + * be expanded to a new array containing all entries. + */ + ignoreFormats?: string[] | undefined; + }, + ): Promise; + + /** + * Validates a single external example. + * + * @param filePathSchema - File-path to the OpenAPI-spec + * @param pathSchema - JSON-path to the schema + * @param filePathExample - File-path to the external example-file + */ + export function validateExample( + filePathSchema: string, + pathSchema: string, + filePathExample: string, + options?: { + /** + * Don't allow properties that are not described in the schema + */ + noAdditionalProperties?: boolean | undefined; + /** + * Make all properties required + */ + allPropertiesRequired?: boolean | undefined; + /** + * List of datatype formats that shall be ignored (to prevent + * "unsupported format" errors). If an Array with only one string is + * provided where the formats are separated with `\n`, the entries will + * be expanded to a new array containing all entries. + */ + ignoreFormats?: string[] | undefined; + }, + ): Promise; +} + +export default OpenApiExamplesValidator;