diff --git a/.changeset/hot-turkeys-perform.md b/.changeset/hot-turkeys-perform.md new file mode 100644 index 000000000..7291f55b6 --- /dev/null +++ b/.changeset/hot-turkeys-perform.md @@ -0,0 +1,6 @@ +--- +"@hey-api/openapi-ts": patch +"openapi-ts-docs": patch +--- + +fix(config): rename exportSchemas to schemas diff --git a/docs/index.md b/docs/index.md index 450e05eb2..0260b4745 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,6 +25,9 @@ features: - icon: 🦴 title: Data Fetching details: Typesafe data with our REST clients. Fetch, axios, angular, node, and xhr are available. + - icon: "{✓}" + title: JSON Schemas + details: Export OpenAPI schemas as JavaScript objects. JSON Schema 2020-12 supported. --- ### Migrating from OpenAPI Typescript Codegen? diff --git a/docs/openapi-ts/configuration.md b/docs/openapi-ts/configuration.md index 41ee5d35b..8349621fe 100644 --- a/docs/openapi-ts/configuration.md +++ b/docs/openapi-ts/configuration.md @@ -150,6 +150,30 @@ export default { } ``` +## JSON Schemas + +By default, `openapi-ts` exports schemas from your OpenAPI specification as plain JavaScript objects. A great use case for schemas is client-side form input validation. + +```ts +import { $Schema } from 'src/client' + +const maxInputLength = $Schema.properties.text.maxLength + +if (userInput.length > maxInputLength) { + throw new Error(`String length cannot exceed ${maxInputLength} characters!`) +} +``` + +If you're using OpenAPI v3.1, your schemas are JSON Schema compliant and can be used with any other tools supporting JSON Schema. However, if you don't need schemas at all, you can disable them with + +```js{4} +export default { + input: 'path/to/openapi.json', + output: 'src/client', + schemas: false, +} +``` + ## Config API You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/types/config.ts) interface. diff --git a/docs/openapi-ts/migrating.md b/docs/openapi-ts/migrating.md index b5d5a64d6..c084a1c92 100644 --- a/docs/openapi-ts/migrating.md +++ b/docs/openapi-ts/migrating.md @@ -27,7 +27,7 @@ This way, you can gradually switch over to the new syntax as you update parts of ### Changes -- `exportSchemas` is `true` by default (set `exportSchemas` to `false` to preserve the old behavior) +- `exportSchemas` is `true` by default (set `exportSchemas` to `false` to preserve the old behavior, in v0.36.0 this has been renamed to `schemas`) - `client` is optional (old behavior preserved, but can be most likely removed) ### Removed diff --git a/packages/openapi-ts/bin/index.js b/packages/openapi-ts/bin/index.js index e7e0bf992..4c979ceee 100755 --- a/packages/openapi-ts/bin/index.js +++ b/packages/openapi-ts/bin/index.js @@ -20,7 +20,6 @@ const params = program .option('--enums ', 'Export enum definitions (javascript, typescript)') .option('--exportCore [value]', 'Write core files to disk') .option('--exportModels [value]', 'Write models to disk') - .option('--exportSchemas [value]', 'Write schemas to disk') .option('--exportServices [value]', 'Write services to disk') .option('--format [value]', 'Process output folder with formatter?') .option('--lint [value]', 'Process output folder with linter?') @@ -28,6 +27,7 @@ const params = program .option('--operationId [value]', 'Use operationd ID?') .option('--postfixServices ', 'Service name postfix') .option('--request ', 'Path to custom request file') + .option('--schemas [value]', 'Write schemas to disk') .option('--serviceResponse [value]', 'Define shape of returned value from service calls') .option('--useDateType [value]', 'Output Date instead of string for the format "date-time" in the models') .option('--useOptions [value]', 'Use options instead of arguments') @@ -64,11 +64,11 @@ async function start() { ...processParams(params, [ 'exportCore', 'exportModels', - 'exportSchemas', 'exportServices', 'format', 'lint', 'operationId', + 'schemas', 'useDateType', 'useOptions', 'write', diff --git a/packages/openapi-ts/src/index.ts b/packages/openapi-ts/src/index.ts index 4e3b56862..0bb1c804a 100644 --- a/packages/openapi-ts/src/index.ts +++ b/packages/openapi-ts/src/index.ts @@ -95,7 +95,6 @@ const getConfig = async (userConfig: UserConfig, dependencies: Dependencies) => experimental = false, exportCore = true, exportModels = true, - exportSchemas = true, exportServices = true, format = true, input, @@ -104,6 +103,7 @@ const getConfig = async (userConfig: UserConfig, dependencies: Dependencies) => operationId = true, postfixServices = 'Service', request, + schemas = true, serviceResponse = 'body', useDateType = false, useOptions = true, @@ -149,7 +149,6 @@ const getConfig = async (userConfig: UserConfig, dependencies: Dependencies) => experimental, exportCore, exportModels, - exportSchemas, exportServices, format, input, @@ -159,6 +158,7 @@ const getConfig = async (userConfig: UserConfig, dependencies: Dependencies) => output, postfixServices, request, + schemas, serviceResponse, useDateType, useOptions, diff --git a/packages/openapi-ts/src/openApi/__tests__/index.spec.ts b/packages/openapi-ts/src/openApi/__tests__/index.spec.ts index 12a6c9f84..c9dee6d03 100644 --- a/packages/openapi-ts/src/openApi/__tests__/index.spec.ts +++ b/packages/openapi-ts/src/openApi/__tests__/index.spec.ts @@ -16,7 +16,6 @@ describe('parse', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: true, input: '', @@ -24,6 +23,7 @@ describe('parse', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/openApi/v2/parser/__tests__/getServices.spec.ts b/packages/openapi-ts/src/openApi/v2/parser/__tests__/getServices.spec.ts index ccf87a2bf..d4bd54a27 100644 --- a/packages/openapi-ts/src/openApi/v2/parser/__tests__/getServices.spec.ts +++ b/packages/openapi-ts/src/openApi/v2/parser/__tests__/getServices.spec.ts @@ -11,7 +11,6 @@ describe('getServices', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -19,6 +18,7 @@ describe('getServices', () => { operationId: false, output: '', postfixServices: 'Service', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/openApi/v3/parser/__tests__/getServices.spec.ts b/packages/openapi-ts/src/openApi/v3/parser/__tests__/getServices.spec.ts index 625ce1813..52e0843c8 100644 --- a/packages/openapi-ts/src/openApi/v3/parser/__tests__/getServices.spec.ts +++ b/packages/openapi-ts/src/openApi/v3/parser/__tests__/getServices.spec.ts @@ -11,7 +11,6 @@ describe('getServices', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -19,6 +18,7 @@ describe('getServices', () => { operationId: true, output: '', postfixServices: 'Service', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/types/config.ts b/packages/openapi-ts/src/types/config.ts index 663ecd52c..abe22ef9e 100644 --- a/packages/openapi-ts/src/types/config.ts +++ b/packages/openapi-ts/src/types/config.ts @@ -33,11 +33,6 @@ export interface UserConfig { * @default true */ exportModels?: boolean | string; - /** - * Generate schemas? - * @default true - */ - exportSchemas?: boolean; /** * Generate services? * @default true @@ -79,6 +74,11 @@ export interface UserConfig { * Path to custom request file */ request?: string; + /** + * Export JSON schemas? + * @default true + */ + schemas?: boolean; /** * Define shape of returned value from service calls * @default 'body' diff --git a/packages/openapi-ts/src/utils/__tests__/handlebars.spec.ts b/packages/openapi-ts/src/utils/__tests__/handlebars.spec.ts index 48e56e5ed..f1ebac723 100644 --- a/packages/openapi-ts/src/utils/__tests__/handlebars.spec.ts +++ b/packages/openapi-ts/src/utils/__tests__/handlebars.spec.ts @@ -12,7 +12,6 @@ describe('registerHandlebarHelpers', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: true, input: '', @@ -20,6 +19,7 @@ describe('registerHandlebarHelpers', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: false, @@ -49,7 +49,6 @@ describe('registerHandlebarTemplates', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: true, input: '', @@ -57,6 +56,7 @@ describe('registerHandlebarTemplates', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: false, diff --git a/packages/openapi-ts/src/utils/write/__tests__/class.spec.ts b/packages/openapi-ts/src/utils/write/__tests__/class.spec.ts index 8ebbef814..edc577d63 100644 --- a/packages/openapi-ts/src/utils/write/__tests__/class.spec.ts +++ b/packages/openapi-ts/src/utils/write/__tests__/class.spec.ts @@ -29,7 +29,6 @@ describe('writeClientClass', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -38,6 +37,7 @@ describe('writeClientClass', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/utils/write/__tests__/client.spec.ts b/packages/openapi-ts/src/utils/write/__tests__/client.spec.ts index 889f1ad9a..2e4ce3a60 100644 --- a/packages/openapi-ts/src/utils/write/__tests__/client.spec.ts +++ b/packages/openapi-ts/src/utils/write/__tests__/client.spec.ts @@ -25,7 +25,6 @@ describe('writeClient', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: true, input: '', @@ -33,6 +32,7 @@ describe('writeClient', () => { operationId: true, output: './dist', postfixServices: 'Service', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: false, diff --git a/packages/openapi-ts/src/utils/write/__tests__/core.spec.ts b/packages/openapi-ts/src/utils/write/__tests__/core.spec.ts index 8b5828b6c..ed0685a5c 100644 --- a/packages/openapi-ts/src/utils/write/__tests__/core.spec.ts +++ b/packages/openapi-ts/src/utils/write/__tests__/core.spec.ts @@ -31,7 +31,6 @@ describe('writeClientCore', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -40,6 +39,7 @@ describe('writeClientCore', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, @@ -73,7 +73,6 @@ describe('writeClientCore', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -82,6 +81,7 @@ describe('writeClientCore', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, @@ -115,7 +115,6 @@ describe('writeClientCore', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -124,6 +123,7 @@ describe('writeClientCore', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/utils/write/__tests__/index.spec.ts b/packages/openapi-ts/src/utils/write/__tests__/index.spec.ts index e5182bcd7..57cfd4ff6 100644 --- a/packages/openapi-ts/src/utils/write/__tests__/index.spec.ts +++ b/packages/openapi-ts/src/utils/write/__tests__/index.spec.ts @@ -24,7 +24,6 @@ describe('writeClientIndex', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -32,6 +31,7 @@ describe('writeClientIndex', () => { operationId: true, output: '', postfixServices: 'Service', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/utils/write/__tests__/models.spec.ts b/packages/openapi-ts/src/utils/write/__tests__/models.spec.ts index 50ac16d0f..7801114e3 100644 --- a/packages/openapi-ts/src/utils/write/__tests__/models.spec.ts +++ b/packages/openapi-ts/src/utils/write/__tests__/models.spec.ts @@ -44,7 +44,6 @@ describe('writeClientModels', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -53,6 +52,7 @@ describe('writeClientModels', () => { operationId: true, output: '', postfixServices: '', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: true, diff --git a/packages/openapi-ts/src/utils/write/__tests__/services.spec.ts b/packages/openapi-ts/src/utils/write/__tests__/services.spec.ts index a3db3d2f8..642f07202 100644 --- a/packages/openapi-ts/src/utils/write/__tests__/services.spec.ts +++ b/packages/openapi-ts/src/utils/write/__tests__/services.spec.ts @@ -36,7 +36,6 @@ describe('writeClientServices', () => { experimental: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, format: false, input: '', @@ -44,6 +43,7 @@ describe('writeClientServices', () => { operationId: true, output: '', postfixServices: 'Service', + schemas: true, serviceResponse: 'body', useDateType: false, useOptions: false, diff --git a/packages/openapi-ts/src/utils/write/client.ts b/packages/openapi-ts/src/utils/write/client.ts index 7a95034be..823007e55 100644 --- a/packages/openapi-ts/src/utils/write/client.ts +++ b/packages/openapi-ts/src/utils/write/client.ts @@ -48,7 +48,7 @@ export const writeClient = async ( }, { dir: '', - enabled: config.exportSchemas, + enabled: config.schemas, fn: writeClientSchemas, }, { diff --git a/packages/openapi-ts/src/utils/write/index.ts b/packages/openapi-ts/src/utils/write/index.ts index cc55fab31..e8f8e80ed 100644 --- a/packages/openapi-ts/src/utils/write/index.ts +++ b/packages/openapi-ts/src/utils/write/index.ts @@ -33,7 +33,7 @@ export const writeClientIndex = async (client: Client, outputPath: string, confi if (config.exportModels) { file.add(compiler.export.all('./models')); } - if (config.exportSchemas) { + if (config.schemas) { file.add(compiler.export.all('./schemas')); } } diff --git a/packages/openapi-ts/test/bin.spec.ts b/packages/openapi-ts/test/bin.spec.ts index b6cad2745..2d474ae0f 100755 --- a/packages/openapi-ts/test/bin.spec.ts +++ b/packages/openapi-ts/test/bin.spec.ts @@ -113,7 +113,7 @@ describe('bin', () => { 'true', '--exportModels', 'true', - '--exportSchemas', + '--schemas', 'true', '--write', 'false', @@ -208,7 +208,7 @@ describe('cli', () => { 'false', '--exportModels', 'false', - '--exportSchemas', + '--schemas', 'false', '--exportServices', 'false', @@ -228,7 +228,7 @@ describe('cli', () => { expect(result.stdout.toString()).toContain('debug: true'); expect(result.stdout.toString()).toContain('exportCore: false'); expect(result.stdout.toString()).toContain('exportModels: false'); - expect(result.stdout.toString()).toContain('exportSchemas: false'); + expect(result.stdout.toString()).toContain('schemas: false'); expect(result.stdout.toString()).toContain('exportServices: false'); expect(result.stdout.toString()).toContain('format: false'); expect(result.stdout.toString()).toContain('lint: false'); @@ -250,7 +250,7 @@ describe('cli', () => { 'true', '--exportModels', 'true', - '--exportSchemas', + '--schemas', 'true', '--exportServices', 'true', @@ -270,7 +270,7 @@ describe('cli', () => { expect(result.stdout.toString()).toContain('debug: true'); expect(result.stdout.toString()).toContain('exportCore: true'); expect(result.stdout.toString()).toContain('exportModels: true'); - expect(result.stdout.toString()).toContain('exportSchemas: true'); + expect(result.stdout.toString()).toContain('schemas: true'); expect(result.stdout.toString()).toContain('exportServices: true'); expect(result.stdout.toString()).toContain('format: true'); expect(result.stdout.toString()).toContain('lint: true'); @@ -291,7 +291,7 @@ describe('cli', () => { '--exportCore', '--exportModels', 'foo', - '--exportSchemas', + '--schemas', '--exportServices', 'bar', '--format', @@ -305,7 +305,7 @@ describe('cli', () => { expect(result.stdout.toString()).toContain('debug: true'); expect(result.stdout.toString()).toContain('exportCore: true'); expect(result.stdout.toString()).toContain("exportModels: 'foo"); - expect(result.stdout.toString()).toContain('exportSchemas: true'); + expect(result.stdout.toString()).toContain('schemas: true'); expect(result.stdout.toString()).toContain("exportServices: 'bar'"); expect(result.stdout.toString()).toContain('format: true'); expect(result.stdout.toString()).toContain('lint: true'); diff --git a/packages/openapi-ts/test/index.spec.ts b/packages/openapi-ts/test/index.spec.ts index 9a7396d74..a039dfb06 100644 --- a/packages/openapi-ts/test/index.spec.ts +++ b/packages/openapi-ts/test/index.spec.ts @@ -21,8 +21,8 @@ describe('OpenAPI v2', () => { enums: 'javascript', exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, + schemas: true, useOptions: true, } as UserConfig, description: 'generate fetch client', @@ -50,8 +50,8 @@ describe('OpenAPI v3', () => { enums: 'javascript', exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, + schemas: true, useOptions: true, } as UserConfig, description: 'generate fetch client', @@ -63,8 +63,8 @@ describe('OpenAPI v3', () => { enums: false, exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, + schemas: true, useOptions: true, } as UserConfig, description: 'generate angular client', @@ -76,8 +76,8 @@ describe('OpenAPI v3', () => { enums: false, exportCore: true, exportModels: false, - exportSchemas: false, exportServices: false, + schemas: false, useOptions: true, } as UserConfig, description: 'generate node client', @@ -89,8 +89,8 @@ describe('OpenAPI v3', () => { enums: false, exportCore: true, exportModels: false, - exportSchemas: false, exportServices: false, + schemas: false, useOptions: true, } as UserConfig, description: 'generate axios client', @@ -102,8 +102,8 @@ describe('OpenAPI v3', () => { enums: false, exportCore: true, exportModels: false, - exportSchemas: false, exportServices: false, + schemas: false, useOptions: true, } as UserConfig, description: 'generate xhr client', @@ -115,8 +115,8 @@ describe('OpenAPI v3', () => { enums: 'javascript', exportCore: false, exportModels: '^ModelWithPattern', - exportSchemas: true, exportServices: false, + schemas: true, useDateType: true, useOptions: true, } as UserConfig, @@ -129,8 +129,8 @@ describe('OpenAPI v3', () => { enums: 'javascript', exportCore: true, exportModels: '^ModelWithString', - exportSchemas: false, exportServices: '^Defaults', + schemas: false, useDateType: true, useOptions: false, } as UserConfig, @@ -143,8 +143,8 @@ describe('OpenAPI v3', () => { enums: 'javascript', exportCore: true, exportModels: '^ModelWithString', - exportSchemas: false, exportServices: '^Defaults', + schemas: false, useDateType: true, useOptions: true, } as UserConfig, @@ -157,9 +157,9 @@ describe('OpenAPI v3', () => { enums: 'javascript', exportCore: true, exportModels: true, - exportSchemas: false, exportServices: true, name: 'ApiClient', + schemas: false, useDateType: true, useOptions: true, } as UserConfig, @@ -172,8 +172,8 @@ describe('OpenAPI v3', () => { enums: 'typescript', exportCore: true, exportModels: true, - exportSchemas: true, exportServices: true, + schemas: true, useOptions: true, } as UserConfig, description: 'generate TypeScript enums', @@ -184,8 +184,8 @@ describe('OpenAPI v3', () => { client: 'fetch', exportCore: false, exportModels: true, - exportSchemas: false, exportServices: false, + schemas: false, } as UserConfig, description: 'generate models', name: 'v3_models',