openapi-ts-json-schema
Advanced tools
openapi-ts-json-schema - npm Package Compare versions
Comparing version 0.5.0 to 0.6.0
@@ -12,3 +12,3 @@ "use strict"; | ||
| const utils_1 = require("./utils"); | ||
| async function openapiToTsJsonSchema({ openApiSchema: openApiSchemaRelative, definitionPathsToGenerateFrom, schemaPatcher, outputPath: providedOutputPath, plugins = [], silent, refHandling = 'inline', }) { | ||
| async function openapiToTsJsonSchema({ openApiSchema: openApiSchemaRelative, definitionPathsToGenerateFrom, schemaPatcher, outputPath: providedOutputPath, plugins = [], silent, refHandling = 'import', }) { | ||
| if (definitionPathsToGenerateFrom.length === 0 && !silent) { | ||
@@ -29,6 +29,7 @@ console.log(`[openapi-ts-json-schema] ⚠️ No schemas will be generated since definitionPathsToGenerateFrom option is empty`); | ||
| await (0, utils_1.clearFolder)(outputPath); | ||
| const bundledOpenApiSchema = await json_schema_ref_parser_1.default.bundle(openApiSchemaPath); | ||
| const schemaParser = new json_schema_ref_parser_1.default(); | ||
| const bundledOpenApiSchema = await schemaParser.bundle(openApiSchemaPath); | ||
| const initialJsonSchema = (0, utils_1.convertOpenApiToJsonSchema)(bundledOpenApiSchema); | ||
| const inlinedRefs = new Map(); | ||
| const dereferencedJsonSchema = await json_schema_ref_parser_1.default.dereference(initialJsonSchema, { | ||
| const dereferencedJsonSchema = await schemaParser.dereference(initialJsonSchema, { | ||
| dereference: { | ||
@@ -63,2 +64,5 @@ // @ts-expect-error onDereference seems not to be properly typed | ||
| }); | ||
| if (refHandling === 'inline' && schemaParser.$refs.circular) { | ||
| throw new Error('[openapi-ts-json-schema] Circular input definition detected. Use "import" or "keep" refHandling option, instead.'); | ||
| } | ||
| const jsonSchema = (0, utils_1.convertOpenApiParameters)(dereferencedJsonSchema); | ||
@@ -65,0 +69,0 @@ const schemaMetaDataMap = new Map(); |
@@ -13,6 +13,7 @@ "use strict"; | ||
| const importedSchema = schemaMetaDataMap.get(ref); | ||
| /* istanbul ignore if: It should not be possible to hit this condition -- @preserve */ | ||
| /* c8 ignore start */ | ||
| if (!importedSchema) { | ||
| throw new Error('[openapi-ts-json-schema] No matching schema found in "schemaMetaDataMap"'); | ||
| } | ||
| /* c8 ignore stop */ | ||
| // Evaluate imported schema relative path from current schema file | ||
@@ -19,0 +20,0 @@ const importedSchemaRelativePath = (0, __1.makeRelativePath)({ |
@@ -15,6 +15,7 @@ "use strict"; | ||
| function refToPath(ref) { | ||
| /* istanbul ignore if: if this condition was true the execution would break before getting to this line -- @preserve */ | ||
| /* c8 ignore start */ | ||
| if (!ref.startsWith('#/')) { | ||
| throw new Error(`[openapi-ts-json-schema] Unsupported ref value: "${ref}"`); | ||
| } | ||
| /* c8 ignore stop */ | ||
| const refPath = ref.replace('#/', ''); | ||
@@ -21,0 +22,0 @@ const schemaName = node_path_1.default.basename(refPath); |
| { | ||
| "name": "openapi-ts-json-schema", | ||
| "version": "0.5.0", | ||
| "version": "0.6.0", | ||
| "description": "OpenAPI to JSON schema generator with TypeScript in mind", | ||
@@ -38,6 +38,7 @@ "main": "./dist/index.js", | ||
| "@fastify/swagger-ui": "^1.9.3", | ||
| "@fastify/type-provider-json-schema-to-ts": "^2.2.2", | ||
| "@fastify/type-provider-json-schema-to-ts": "^3.0.0", | ||
| "@tsconfig/node18": "^18.2.0", | ||
| "@types/lodash.get": "^4.4.7", | ||
| "@vitest/coverage-istanbul": "^0.34.1", | ||
| "@vitest/coverage-istanbul": "^1.1.0", | ||
| "@vitest/coverage-v8": "^1.1.0", | ||
| "fastify": "^4.23.2", | ||
@@ -49,3 +50,3 @@ "rimraf": "^5.0.1", | ||
| "typescript": "^5.1.6", | ||
| "vitest": "^0.34.1" | ||
| "vitest": "^1.1.0" | ||
| }, | ||
@@ -52,0 +53,0 @@ "engines": { |
@@ -7,8 +7,8 @@ # openapi-ts-json-schema | ||
| Generate **TypeScript JSON schema** files (`.ts`) from **OpenAPI** definitions on Node.js. | ||
| Generate **TypeScript JSON schema** files (`.ts` modules with `as const` assertions) from **OpenAPI** definitions. | ||
| TypeScript JSON schemas can natively be used for: | ||
| TypeScript JSON schemas can be used for: | ||
| - Runtime data validation (with any JSON schema validator like [Ajv](https://ajv.js.org/)) | ||
| - Static TypeScript type check (with [`json-schema-to-ts`](https://github.com/ThomasAribart/json-schema-to-ts)) | ||
| - Inferring TypeScript type definitions from OpenApi definitions (with [`json-schema-to-ts`](https://github.com/ThomasAribart/json-schema-to-ts)) | ||
| - Runtime data validation with TypeScript type inferring (with any JSON schema validator like [Ajv](https://ajv.js.org/)) | ||
@@ -44,3 +44,3 @@ Given an OpenAPI definition file, `openapi-ts-json-schema` will: | ||
| ...then use them in your code: | ||
| ...and use them in your TS project: | ||
@@ -67,3 +67,3 @@ ```ts | ||
| | **definitionPathsToGenerateFrom** _(required)_ | `string[]` | OpenApi definition object paths to generate the JSON schemas from. Only matching paths will be generated. (Supports dot notation: `["components.schemas"]`). | - | | ||
| | **refHandling** | `"inline" \| "import" \| "keep"` | `"inline"`: inline `$ref` schemas. <br/>`"import"`: generate and import `$ref` schemas.<br/>`"keep"`: keep `$ref` value. | `"inline"` | | ||
| | **refHandling** | `"import" \| "inline" \| "keep"` | `"import"`: generate and import `$ref` schemas.<br/>`"inline"`: inline `$ref` schemas.<br/>`"keep"`: keep `$ref` values. | `"import"` | | ||
| | **schemaPatcher** | `(params: { schema: JSONSchema }) => void` | Dynamically patch generated JSON schemas. The provided function will be invoked against every single JSON schema node. | - | | ||
@@ -74,10 +74,18 @@ | **outputPath** | `string` | Path where the generated schemas will be saved. Defaults to `/schemas-autogenerated` in same directory as provided `openApiSchema`. | - | | ||
| ### Notes | ||
| ## Notes | ||
| Generated TypeScript JSON schema path names get escaped in order to be valid file system names. | ||
| Take a look at the [Developer's notes](./docs/developer-notes.md) for a few more in-depth explanations. | ||
| Circular `$ref`s can be technically resolved with "import" `refHandling` option. But TS will stop the type recursion and type the schema as `any` (error `ts(7022)`). See [relevant tests](https://github.com/toomuchdesign/openapi-ts-json-schema/blob/master/test/circularReference.test.ts). | ||
| ### `$ref`s handling | ||
| Take a look at the [Developer's notes](./docs/developer-notes.md) for a few more in-depth explanations. | ||
| `openapi-ts-json-schema` provides 3 different strategies to handle OpenApi `$ref` properties configurable via the `refHandling` option: | ||
| - `import`: `$ref` values get replaced with a local variable pointing to module of the generated target definition | ||
| - `inline`: `$ref` values get recursively replaced with inline copies of the target definition. This produces self-contained standalone schemas with usually repeated inline definitions | ||
| - `keep`: `$ref` values get preserved. | ||
| ### Circular `$ref`s | ||
| Circular `$ref`s can be technically resolved with "import" `refHandling` option. However, TS engine will interrupt type recursion and type the schema as `any` (error `ts(7022)`). See [relevant tests](https://github.com/toomuchdesign/openapi-ts-json-schema/blob/master/test/circularReference.test.ts). | ||
| ## Return values | ||
@@ -134,2 +142,3 @@ | ||
| - Improve external `#ref`s handling | ||
| - Consider implementing a strategy to stop circular reference recursion after a given amount of nesting | ||
@@ -136,0 +145,0 @@ [ci-badge]: https://github.com/toomuchdesign/openapi-ts-json-schema/actions/workflows/ci.yml/badge.svg |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by1.62%
49501
- Lines of code
- increased by0.74%
812
- Number of lines in readme file
- increased by6.57%
146
Worsened metrics
- Dev dependency count
- increased by7.14%
15