Merge pull request #288 from hey-api/docs/json-schemas

fix(config): rename exportSchemas to schemas
hey-api · Apr 8, 2024 · 25ba56f · 25ba56f
2 parents cd8970f + 443231b
commit 25ba56f
Show file tree

Hide file tree

Showing 21 changed files with 77 additions and 44 deletions.
diff --git a/.changeset/hot-turkeys-perform.md 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
@@ -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
@@ -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
@@ -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
@@ -20,14 +20,14 @@ const params = program
     .option('--enums <value>', '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?')
     .option('--name <value>', 'Custom client class name')
     .option('--operationId [value]', 'Use operationd ID?')
     .option('--postfixServices <value>', 'Service name postfix')
     .option('--request <value>', '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
@@ -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
@@ -16,14 +16,14 @@ describe('parse', () => {
         experimental: false,
         exportCore: true,
         exportModels: true,
-        exportSchemas: true,
         exportServices: true,
         format: true,
         input: '',
         lint: false,
         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
@@ -11,14 +11,14 @@ describe('getServices', () => {
             experimental: false,
             exportCore: true,
             exportModels: true,
-            exportSchemas: true,
             exportServices: true,
             format: false,
             input: '',
             lint: false,
             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
@@ -11,14 +11,14 @@ describe('getServices', () => {
             experimental: false,
             exportCore: true,
             exportModels: true,
-            exportSchemas: true,
             exportServices: true,
             format: false,
             input: '',
             lint: false,
             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
@@ -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
@@ -12,14 +12,14 @@ describe('registerHandlebarHelpers', () => {
             experimental: false,
             exportCore: true,
             exportModels: true,
-            exportSchemas: true,
             exportServices: true,
             format: true,
             input: '',
             lint: false,
             operationId: true,
             output: '',
             postfixServices: '',
+            schemas: true,
             serviceResponse: 'body',
             useDateType: false,
             useOptions: false,
@@ -49,14 +49,14 @@ describe('registerHandlebarTemplates', () => {
             experimental: false,
             exportCore: true,
             exportModels: true,
-            exportSchemas: true,
             exportServices: true,
             format: true,
             input: '',
             lint: false,
             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
@@ -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
@@ -25,14 +25,14 @@ describe('writeClient', () => {
             experimental: false,
             exportCore: true,
             exportModels: true,
-            exportSchemas: true,
             exportServices: true,
             format: true,
             input: '',
             lint: false,
             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
@@ -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
@@ -24,14 +24,14 @@ describe('writeClientIndex', () => {
             experimental: false,
             exportCore: true,
             exportModels: true,
-            exportSchemas: true,
             exportServices: true,
             format: false,
             input: '',
             lint: false,
             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
@@ -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
@@ -36,14 +36,14 @@ describe('writeClientServices', () => {
                 experimental: false,
                 exportCore: true,
                 exportModels: true,
-                exportSchemas: true,
                 exportServices: true,
                 format: false,
                 input: '',
                 lint: false,
                 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
@@ -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
@@ -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'));
         }
     }