diff --git a/CHANGELOG.md b/CHANGELOG.md index acf6a0a..98d8b60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ ## unreleased +- Add type definitions for openapi-format + ## [1.23.2] - 2024-09-16 - Filter - handle inverseFlagValues removal of nested array values diff --git a/package-lock.json b/package-lock.json index bf38dbf..eb9c795 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,7 +18,8 @@ "openapi-format": "bin/cli.js" }, "devDependencies": { - "jest": "^29.7.0" + "jest": "^29.7.0", + "openapi-types": "^12.1.3" }, "engines": { "node": ">=18" @@ -2908,6 +2909,12 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/openapi-types": { + "version": "12.1.3", + "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-12.1.3.tgz", + "integrity": "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==", + "dev": true + }, "node_modules/p-limit": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", @@ -5763,6 +5770,12 @@ "mimic-fn": "^2.1.0" } }, + "openapi-types": { + "version": "12.1.3", + "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-12.1.3.tgz", + "integrity": "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==", + "dev": true + }, "p-limit": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", diff --git a/package.json b/package.json index ff4c1b4..8637240 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,7 @@ "license": "MIT", "author": "Tim Haselaars", "main": "openapi-format.js", + "types": "types/openapi-format.d.ts", "bin": { "openapi-format": "bin/cli.js" }, @@ -38,7 +39,8 @@ "neotraverse": "^0.6.18" }, "devDependencies": { - "jest": "^29.7.0" + "jest": "^29.7.0", + "openapi-types": "^12.1.3" }, "engines": { "node": ">=18" @@ -59,6 +61,7 @@ "defaultFilter.json", "defaultSort.json", "defaultSortComponents.json", + "types/openapi-format.d.ts", "package-lock.json" ], "directories": { diff --git a/types/openapi-format.d.ts b/types/openapi-format.d.ts new file mode 100644 index 0000000..6b9689b --- /dev/null +++ b/types/openapi-format.d.ts @@ -0,0 +1,218 @@ +// openapi-format.d.ts + +declare module 'openapi-format' { + import { OpenAPIV3 } from 'openapi-types' + + interface OpenAPISortSet { + root?: Array<'openapi' | 'info' | 'servers' | 'paths' | 'components' | 'tags' | 'x-tagGroups' | 'externalDocs'> + get?: Array<'operationId' | 'summary' | 'description' | 'parameters' | 'requestBody' | 'responses'> + post?: Array<'operationId' | 'summary' | 'description' | 'parameters' | 'requestBody' | 'responses'> + put?: Array<'operationId' | 'summary' | 'description' | 'parameters' | 'requestBody' | 'responses'> + patch?: Array<'operationId' | 'summary' | 'description' | 'parameters' | 'requestBody' | 'responses'> + delete?: Array<'operationId' | 'summary' | 'description' | 'parameters' | 'requestBody' | 'responses'> + parameters?: Array<'name' | 'in' | 'description' | 'required' | 'schema'> + requestBody?: Array<'description' | 'required' | 'content'> + responses?: Array<'description' | 'headers' | 'content' | 'links'> + content?: Array + components?: Array<'parameters' | 'schemas'> + schema?: Array<'description' | 'type' | 'items' | 'properties' | 'format' | 'example' | 'default'> + schemas?: Array<'description' | 'type' | 'items' | 'properties' | 'format' | 'example' | 'default'> + properties?: Array<'description' | 'type' | 'items' | 'format' | 'example' | 'default' | 'enum'> + sortPathsBy?: 'original' | 'path' | 'tags' + } + + interface OpenAPISortOptions { + sortSet: OpenAPISortSet + sortComponentsSet?: string[] + } + + interface OpenAPIFilterSet { + methods?: string[] + tags?: string[] + operationIds?: string[] + operations?: string[] + flags?: string[] + flagValues?: string[] + inverseMethods?: string[] + inverseTags?: string[] + inverseOperationIds?: string[] + responseContent?: string[] + inverseResponseContent?: string[] + unusedComponents?: string[] + stripFlags?: string[] + preserveEmptyObjects?: boolean | string[]; + } + + interface OpenAPICasingOptions { + casingSet?: OpenAPICasingSet + } + + interface OpenAPICasingSet { + operationId?: string + properties?: string + parametersQuery?: string + parametersHeader?: string + parametersPath?: string + componentsExamples?: string + componentsSchemas?: string + componentsHeaders?: string + componentsResponses?: string + componentsRequestBodies?: string + componentsSecuritySchemes?: string + componentsParametersQuery?: string + componentsParametersHeader?: string + componentsParametersPath?: string + } + + interface OpenAPIGenerateOptions { + generateSet?: OpenAPIGenerateSet + } + + interface OpenAPIGenerateSet { + operationIdTemplate?: string + overwriteExisting?: boolean + } + + interface OpenAPIFilterOptions { + filterSet?: OpenAPIFilterSet + defaultFilter?: OpenAPIFilterSet + } + + interface OpenAPIResult { + data: OpenAPIV3.Document | string + resultData: Record + } + + export interface AnalyzeOpenApiResult { + operations?: string[]; + methods?: string[]; + paths?: string[]; + flags?: string[]; + operationIds?: string[]; + flagValues?: string[]; + responseContent?: string[]; + tags?: string[]; + [key: string]: string[] | undefined; + } + + export interface WriteFileOptions { + format?: string; + keepComments?: boolean; + yamlComments?: Record; + lineWidth?: string | number; + mode?: string; + } + + /** + * Sorts the properties of an OpenAPI document according to the specified sort configuration. + * @param {OpenAPIV3.Document} oaObj - The OpenAPI document to be sorted. + * @param {OpenAPISortOptions} options - The sorting options. + * @returns {Promise} The sorted OpenAPI document. + */ + export function openapiSort( + oaObj: OpenAPIV3.Document, + options: OpenAPISortOptions + ): Promise + + /** + * Filters the properties of an OpenAPI document based on the specified filter configuration. + * @param {OpenAPIV3.Document} oaObj - The OpenAPI document to be filtered. + * @param {OpenAPIFilterOptions} options - The filtering options. + * @returns {Promise} The filtered OpenAPI document. + */ + export function openapiFilter( + oaObj: OpenAPIV3.Document, + options: OpenAPIFilterOptions + ): Promise + + /** + * Generate elements for an OpenAPI document based on the specified generate configuration. + * @param {OpenAPIV3.Document} oaObj - The OpenAPI document. + * @param {OpenAPIGenerateOptions} options - The generate options. + * @returns {Promise} The enriched OpenAPI document. + */ + export function openapiGenerate( + oaObj: OpenAPIV3.Document, + options: OpenAPIGenerateOptions + ): Promise + + /** + * Change the case of properties an OpenAPI document based on the specified casing configuration. + * @param {OpenAPIV3.Document} oaObj - The OpenAPI document. + * @param {OpenAPICasingOptions} options - The casing options. + * @returns {Promise} The cased OpenAPI document. + */ + export function openapiChangeCase( + oaObj: OpenAPIV3.Document, + options: OpenAPICasingOptions + ): Promise + + /** + * Parses a JSON or YAML file into a JavaScript object. + * @param {string} filePath - The path to the JSON or YAML file. + * @param {Record} [options] - Additional parsing options. + * @returns {Promise>} The parsed data object. + */ + export function parseFile( + filePath: string, + options?: Record + ): Promise> + + /** + * Parses a JSON or YAML string into a JavaScript object. + * @param {string} input - The JSON or YAML string. + * @param {Record} [options] - Additional parsing options. + * @returns {Promise>} The parsed data object. + */ + export function parseString( + input: string, + options?: Record + ): Promise> + + /** + * Detects the format of a given string as either JSON or YAML. + * @param {string} input - The string to detect the format of. + * @returns {Promise<'json' | 'yaml' | 'unknown'>} The detected format. + */ + export function detectFormat( + input: string, + ): Promise<'json' | 'yaml' | 'unknown'> + + /** + * Writes a JavaScript object to a file in JSON or YAML format. + * @param {string} filePath - The path to the output file. + * @param {Record | OpenAPIV3.Document} data - The data object to write. + * @param {WriteFileOptions} [options] - Additional write options. + * @returns {Promise} Resolves when the file has been written. + */ + export function writeFile( + filePath: string, + data: Record, + options?: WriteFileOptions + ): Promise; + /** + * Changes the case of a given string to the specified case type. + * @param {string} valueAsString - The input string to change the case of. + * @param {string} caseType - The target case type (e.g., 'camelCase', 'pascalCase', 'kebabCase', 'snakeCase'). + * @returns {string} The string with the specified case. + */ + export function changeCase(valueAsString: string, caseType: string): string + + /** + * Analyze the OpenAPI document. + * @param {OpenAPIV3.Document} oaObj - The OpenAPI document as a JSON object. + * @returns {AnalyzeOpenApiResult} + */ + export function analyzeOpenApi(oaObj: Record | OpenAPIV3.Document): AnalyzeOpenApiResult + + /** + * Converts any document to a string representation (e.g., JSON or YAML). + * @param {T} document - The document to convert. + * @param {Record} [options] - Additional stringification options. + * @returns {Promise} The string representation of the document. + */ + export function stringify>( + document: T, + options?: Record + ): Promise; +} diff --git a/utils/file.js b/utils/file.js index 8c8520f..5da5414 100644 --- a/utils/file.js +++ b/utils/file.js @@ -99,7 +99,7 @@ async function parseFile(filePath, options = {}) { } /** - * Converts an data object to a JSON/YAML string representation. + * Converts a data object to a JSON/YAML string representation. * @param obj Data object. * @param options Stringify options * @returns {Promise<*>} Stringified data.