You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .changeset/rude-jokes-grin.md
+6-4
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,10 @@
2
2
"openapi-typescript": major
3
3
---
4
4
5
-
⚠️ **Breaking**: Drop auth/fetching options in favor of Redocly CLI’s
5
+
⚠️ **Breaking**: Changing of several CLI flags and Node.js API options
6
6
7
-
- The `auth`, `httpHeaders`, `httpMethod`, and `fetch` options were all removed from the CLI and Node.js API
8
-
- To migrate, you’ll need to create a [redocly.yaml config](https://redocly.com/docs/cli/configuration/) that specifies your auth options [in the http setting](https://redocly.com/docs/cli/configuration/#resolve-non-public-or-non-remote-urls)
9
-
- Worth noting your `redocly.yaml` config will be respected for any other related settings
7
+
- The `--auth`, `--httpHeaders`, `--httpMethod`, and `fetch` (Node.js-only) options were all removed from the CLI and Node.js API
8
+
- To migrate, you’ll need to create a [redocly.yaml config](https://redocly.com/docs/cli/configuration/) that specifies your auth options [in the http setting](https://redocly.com/docs/cli/configuration/#resolve-non-public-or-non-remote-urls)
9
+
- You can also set your fetch client in redocly.yaml as well.
10
+
-`--immutable-types` has been renamed to `--immutable`
11
+
-`--support-array-length` has been renamed to `--array-length`
⚠️ **Breaking**: Remove globbing schemas in favor of `redocly.yaml` config. Specify multiple schemas with outputs in there instead. See [Multiple schemas](https://openapi-ts.pages.dev/docs/cli/#multiple-schemas) for more info.
Copy file name to clipboardExpand all lines: docs/src/content/docs/about.md
-1
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,6 @@ description: Additional info about this project
24
24
25
25
1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
26
26
1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like <ahref="https://www.typescriptlang.org/docs/handbook/enums.html"target="_blank"rel="noopener noreferrer">enums</a>).
27
-
1. Don’t validate schemas; there are existing libraries for that like <ahref="https://redocly.com/docs/cli/commands/lint/"target="_blank"rel="noopener noreferrer">Redocly</a>.
28
27
1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
29
28
1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
30
29
1. Support fetching OpenAPI schemas from files as well as local and remote servers.
Copy file name to clipboardExpand all lines: docs/src/content/docs/cli.md
+73-36
Original file line number
Diff line number
Diff line change
@@ -3,60 +3,97 @@ title: CLI
3
3
description: openapi-typescript CLI usage
4
4
---
5
5
6
-
The CLI is the most common way to use openapi-typescript. The CLI can parse JSON and YAML (via <ahref="https://www.npmjs.com/package/js-yaml"target="_blank"rel="noopener noreferrer">js-yaml</a>). It can parse local and remote schemas (and even supports basic auth).
6
+
The CLI is the most common way to use openapi-typescript. The CLI can parse JSON and YAML, and even validates your schemas using the [Redocly CLI](https://redocly.com/docs/cli/commands/lint/). It can parse local and remote schemas (and even supports basic auth).
7
7
8
-
## Reading schemas
8
+
## Transforming an OpenAPI schema to TypeScript
9
+
10
+
### Single schema
11
+
12
+
The simplest way to transform schemas is by specifying an input schema (JSON or YAML), followed by `--output` (`-o`) where you’d like the output to be saved:
To transform multiple schemas, create a `redocly.yaml` file in the root of your project with [APIs defined](https://redocly.com/docs/cli/configuration/). Under `apis`, give each schema a unique name and optionally a version (the name doesn’t matter, so long as it’s unique). Set the `root` value to your schema’s entry point—this will act as the main input. For the output, set it with `openapi-ts.output`:
29
+
30
+
```yaml
31
+
apis:
32
+
core@v2:
33
+
root: ./openapi/openapi.yaml
34
+
openapi-ts:
35
+
output: ./openapi/openapi.ts
36
+
external@v1:
37
+
root: ./openapi/external.yaml
38
+
openapi-ts:
39
+
output: ./openapi/openapi.ts
40
+
```
41
+
42
+
Whenver you have a `redocly.yaml` file in your project with `apis`, you can omit the input/output parameters in the CLI:
> ⚠️ In previous versions globbing was supported, but that has been **deprecated** in v7 in favor of `redocly.yaml`. You’ll be able to control per-schema output locations better, as well as getting unique per-schema settings.
49
+
50
+
## Redoc config
51
+
52
+
A `redocly.yaml` file isn’t required to use openapi-typescript. By default it extends the `"minimal"` built-in config. But it is recommended if you want to have custom validation rules (or build types for [multiple schemas](#multiple-schemas)). The CLI will try to automatically find a `redocly.yaml` in the root of your project, but you can also provide its location with the `--redoc` flag:
You can read more about the Redoc’s configuration options [in their docs](https://redocly.com/docs/cli/configuration/).
59
+
60
+
## Auth
61
+
62
+
Authentication for non-public schemas is handled in your [Redocly config](https://redocly.com/docs/cli/configuration/#resolve-non-public-or-non-remote-urls). You can add headers and basic authentication like so:
|`--help`||| Display inline help message and exit |
43
-
|`--version`||| Display this library’s version and exit |
44
-
|`--output [location]`|`-o`| (stdout) | Where should the output file be saved? |
45
-
|`--auth [token]`||| Provide an auth token to be passed along in the request (only if accessing a private schema) |
46
-
|`--header`|`-x`|| Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the `key: value` pattern |
47
-
|`--headers-object="{…}"`|`-h`|| Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over `--header`|
48
-
|`--http-method`|`-m`|`GET`| Provide the HTTP Verb/Method for fetching a schema from a remote URL |
49
-
|`--immutable-types`||`false`| Generates immutable types (readonly properties and readonly array) |
50
-
|`--additional-properties`||`false`| Allow arbitrary properties for all schema objects without `additionalProperties: false`|
51
-
|`--empty-objects-unknown`||`false`| Allow arbitrary properties for schema objects with no specified properties, and no specified `additionalProperties`|
52
-
|`--default-non-nullable`||`false`| Treat schema objects with default values as non-nullable |
53
-
|`--export-type`|`-t`|`false`| Export `type` instead of `interface`|
54
-
|`--path-params-as-types`||`false`| Allow dynamic string lookups on the `paths` object |
55
-
|`--support-array-length`||`false`| Generate tuples using array `minItems` / `maxItems`|
| `--additional-properties` | | `false` | Allow arbitrary properties for all schema objects without `additionalProperties: false` |
88
+
| `--empty-objects-unknown` | | `false` | Allow arbitrary properties for schema objects with no specified properties, and no specified `additionalProperties` |
89
+
| `--default-non-nullable` | | `false` | Treat schema objects with default values as non-nullable |
Copy file name to clipboardExpand all lines: docs/src/content/docs/introduction.md
+6-6
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ npm i -D openapi-typescript
34
34
35
35
## Basic usage
36
36
37
-
First, generate a local type file by running `npx openapi-typescript`:
37
+
First, generate a local type file by running `npx openapi-typescript`, first specifying your input schema (JSON or YAML), and where you’d like the `--output` (`-o`) to be saved:
> ⚠️ Be sure to <ahref="https://redocly.com/docs/cli/commands/lint/"target="_blank"rel="noopener noreferrer">validate your schemas</a>! openapi-typescript will err on invalid schemas.
50
-
51
-
Then, import schemas from the generated file like so:
49
+
Then in your TypeScript project, import types where needed:
0 commit comments