|
| 1 | +--- |
| 2 | +sidebar_position: 3 |
| 3 | +--- |
| 4 | + |
| 5 | +# Configuration |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +You need to configure the generator to: |
| 10 | + |
| 11 | +- Correctly interpret `io-ts` types from external packages. |
| 12 | +- Define OpenAPI schemas for custom `io-ts` codecs that can't be automatically derived |
| 13 | + from the Abstract Syntax Tree (AST). |
| 14 | + |
| 15 | +## Preparing external types packages |
| 16 | + |
| 17 | +To process `io-ts` types imported from other npm packages, ensure the following in the |
| 18 | +external package's `package.json`: |
| 19 | + |
| 20 | +1. Include source code in the published npm bundle by adding the source directory to the |
| 21 | + `files` array: |
| 22 | + |
| 23 | + ```json |
| 24 | + // package.json of the external types package |
| 25 | + { |
| 26 | + "name": "my-external-types", |
| 27 | + "version": "1.0.0", |
| 28 | + "files": [ |
| 29 | + "dist/", |
| 30 | + "src/" // Include source code |
| 31 | + ], |
| 32 | + "main": "dist/index.js", |
| 33 | + "types": "dist/index.d.ts", |
| 34 | + "source": "src/index.ts" // Add this field |
| 35 | + // ... rest of package.json |
| 36 | + } |
| 37 | + ``` |
| 38 | + |
| 39 | +2. Specify the source entry point using the `source` field (for example, |
| 40 | + `"source": "src/index.ts"`) |
| 41 | + |
| 42 | +## Defining custom codec schemas |
| 43 | + |
| 44 | +For custom `io-ts` codecs (such as those using `new t.Type(...)` or complex types not |
| 45 | +directly supported), you must define schemas manually using one of these methods: |
| 46 | + |
| 47 | +### Method 1: Via openapi-gen.config.js (recommended for type authors) |
| 48 | + |
| 49 | +You can define schemas directly within the package that declares the custom codecs: |
| 50 | + |
| 51 | +1. Create a file named `openapi-gen.config.js` in the root of the types package |
| 52 | + |
| 53 | +2. Update the package's `package.json` to include: |
| 54 | + |
| 55 | +- The `customCodecFile` field pointing to this file |
| 56 | +- The config file in the `files` array |
| 57 | + |
| 58 | + ```json |
| 59 | + // package.json of the types package defining custom codecs |
| 60 | + { |
| 61 | + "name": "my-custom-codec-package", |
| 62 | + // ... |
| 63 | + "files": [ |
| 64 | + "dist/", |
| 65 | + "src/", |
| 66 | + "openapi-gen.config.js" // Include the config file |
| 67 | + ], |
| 68 | + "customCodecFile": "openapi-gen.config.js" // Point to the file |
| 69 | + // ... |
| 70 | + } |
| 71 | + ``` |
| 72 | + |
| 73 | +3. Structure the `openapi-gen.config.js` file as follows: |
| 74 | + |
| 75 | + ```javascript |
| 76 | + // openapi-gen.config.js |
| 77 | + module.exports = (E) => { |
| 78 | + return { |
| 79 | + // Key matches the exported codec name (e.g., export const MyCustomString = ...) |
| 80 | + MyCustomString: () => |
| 81 | + E.right({ |
| 82 | + type: 'string', |
| 83 | + format: 'custom-format', |
| 84 | + description: 'A custom string type definition', |
| 85 | + }), |
| 86 | + AnotherCustomType: () => |
| 87 | + E.right({ |
| 88 | + type: 'object', |
| 89 | + properties: { |
| 90 | + /* ... */ |
| 91 | + }, |
| 92 | + }), |
| 93 | + // ... other custom codec definitions |
| 94 | + }; |
| 95 | + }; |
| 96 | + ``` |
| 97 | + |
| 98 | +The exported function receives the `fp-ts/Either` namespace (`E`) as an argument. You |
| 99 | +should return an object where: |
| 100 | + |
| 101 | +- Keys are the exported names of your custom codecs |
| 102 | +- Values are functions that return `E.right()` with an OpenAPI schema object |
| 103 | + |
| 104 | +### Method 2: Via --codec-file option (for consumers) |
| 105 | + |
| 106 | +You can define schemas in a configuration file within your project and pass the file |
| 107 | +path via the `--codec-file` option: |
| 108 | + |
| 109 | +1. Create a JavaScript file (for example, `custom-codecs.js`) |
| 110 | + |
| 111 | +2. Structure the file similarly to Method 1, but group definitions by package: |
| 112 | + |
| 113 | + ```javascript |
| 114 | + // custom-codecs.js |
| 115 | + module.exports = (E) => { |
| 116 | + return { |
| 117 | + 'io-ts-bigint': { |
| 118 | + // Package name |
| 119 | + BigIntFromString: () => E.right({ type: 'string', format: 'bigint' }), |
| 120 | + NonZeroBigIntFromString: () => |
| 121 | + E.right({ type: 'string', format: 'bigint' /* constraints */ }), |
| 122 | + // ... other codecs from 'io-ts-bigint' |
| 123 | + }, |
| 124 | + 'my-other-custom-package': { |
| 125 | + // Another package |
| 126 | + SomeType: () => E.right({ type: 'number', format: 'float' }), |
| 127 | + }, |
| 128 | + // ... other packages |
| 129 | + }; |
| 130 | + }; |
| 131 | + ``` |
| 132 | + |
| 133 | +In this structure: |
| 134 | + |
| 135 | +- Keys of the top-level object are package names |
| 136 | +- Values are objects that map codec names to their schema definitions |
| 137 | + |
| 138 | +3. Run the generator with the `--codec-file` option: |
| 139 | + |
| 140 | + ```shell |
| 141 | + npx openapi-generator --codec-file ./custom-codecs.js src/index.ts |
| 142 | + ``` |
0 commit comments