Use Redocly APIs config

openapi-ts · Oct 4, 2023 · fbaf96d · fbaf96d
1 parent 312b7ba
commit fbaf96d
Show file tree

Hide file tree

Showing 62 changed files with 2,375 additions and 1,999 deletions.
diff --git a/.changeset/rude-jokes-grin.md b/.changeset/rude-jokes-grin.md
@@ -2,8 +2,10 @@
 "openapi-typescript": major
 ---
 
-⚠️ **Breaking**: Drop auth/fetching options in favor of Redocly CLI’s
+⚠️ **Breaking**: Changing of several CLI flags and Node.js API options
 
-- The `auth`, `httpHeaders`, `httpMethod`, and `fetch` options were all removed from the CLI and Node.js API
-- 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)
-- Worth noting your `redocly.yaml` config will be respected for any other related settings
+- The `--auth`, `--httpHeaders`, `--httpMethod`, and `fetch` (Node.js-only) options were all removed from the CLI and Node.js API
+  - 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)
+  - You can also set your fetch client in redocly.yaml as well.
+- `--immutable-types` has been renamed to `--immutable`
+- `--support-array-length` has been renamed to `--array-length`
diff --git a/.changeset/shaggy-windows-worry.md b/.changeset/shaggy-windows-worry.md
@@ -0,0 +1,5 @@
+---
+"openapi-typescript": major
+---
+
+⚠️ **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.
diff --git a/.changeset/short-llamas-listen.md b/.changeset/short-llamas-listen.md
@@ -2,4 +2,4 @@
 "openapi-typescript": minor
 ---
 
-✨ **Feature:** allow configuration of schemas via `apis` key in redocly.config.yaml (see https://redocly.com/docs/cli/configuration/)
+✨ **Feature:** allow configuration of schemas via `apis` key in redocly.config.yaml. [See docs](https://openapi-ts.pages.dev/cli/) for more info.
diff --git a/docs/package.json b/docs/package.json
@@ -10,26 +10,26 @@
     "update-contributors": "node scripts/update-contributors.js"
   },
   "dependencies": {
-    "@algolia/client-search": "^4.19.1",
+    "@algolia/client-search": "^4.20.0",
     "@astrojs/preact": "^2.2.2",
-    "@astrojs/react": "^2.2.2",
-    "@docsearch/css": "^3.5.1",
-    "@docsearch/react": "^3.5.1",
-    "@types/react": "^18.2.20",
-    "@types/react-dom": "^18.2.7",
-    "astro": "^2.10.9",
-    "preact": "^10.17.0",
+    "@astrojs/react": "^3.0.2",
+    "@docsearch/css": "^3.5.2",
+    "@docsearch/react": "^3.5.2",
+    "@types/react": "^18.2.24",
+    "@types/react-dom": "^18.2.8",
+    "astro": "^3.2.2",
+    "preact": "^10.18.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "sass": "^1.65.1"
+    "sass": "^1.68.0"
   },
   "devDependencies": {
     "@astrojs/sitemap": "^2.0.2",
-    "@cobalt-ui/cli": "^1.4.1",
-    "@cobalt-ui/plugin-sass": "^1.2.3",
-    "@types/node": "^20.5.0",
+    "@cobalt-ui/cli": "^1.6.0",
+    "@cobalt-ui/plugin-sass": "^1.3.0",
+    "@types/node": "^20.8.2",
     "html-escaper": "^3.0.3",
     "typescript": "^5.2.2",
-    "vite-plugin-sass-dts": "^1.3.9"
+    "vite-plugin-sass-dts": "^1.3.11"
   }
 }
diff --git a/docs/src/content/docs/about.md b/docs/src/content/docs/about.md
@@ -24,7 +24,6 @@ description: Additional info about this project
 
 1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
 1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like <a href="https://www.typescriptlang.org/docs/handbook/enums.html" target="_blank" rel="noopener noreferrer">enums</a>).
-1. Don’t validate schemas; there are existing libraries for that like <a href="https://redocly.com/docs/cli/commands/lint/" target="_blank" rel="noopener noreferrer">Redocly</a>.
 1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
 1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
 1. Support fetching OpenAPI schemas from files as well as local and remote servers.

diff --git a/docs/src/content/docs/advanced.md b/docs/src/content/docs/advanced.md
@@ -185,7 +185,7 @@ $ DEBUG=openapi-ts:* npx openapi-typescript schema.yaml -o my-types.ts
 
 To only see certain types of debug messages, you can set `DEBUG=openapi-ts:[scope]` instead. Valid scopes are `redoc`, `lint`, `bundle`, and `ts`.
 
-Note that debug messages will be suppressed if using the CLI and outputting via `stdout`.
+Note that debug messages will be suppressed if the output is `stdout`.
 
 ## Tips
 

diff --git a/docs/src/content/docs/cli.md b/docs/src/content/docs/cli.md
@@ -3,60 +3,97 @@ title: CLI
 description: openapi-typescript CLI usage
 ---
 
-The CLI is the most common way to use openapi-typescript. The CLI can parse JSON and YAML (via <a href="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).
+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).
 
-## Reading schemas
+## Transforming an OpenAPI schema to TypeScript
+
+### Single schema
+
+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:
 
 ```bash
 npx openapi-typescript schema.yaml -o schema.ts
 
-# 🚀 schema.yaml -> schema.ts [7ms]
+# 🚀 schema.yaml -> schema.ts [50ms]
 ```
 
-### Globbing local schemas
-
 ```bash
-npx openapi-typescript "specs/**/*.yaml" -o schemas/
+npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml -o petstore.d.ts
 
-# 🚀 specs/one.yaml -> schemas/specs/one.ts [7ms]
-# 🚀 specs/two.yaml -> schemas/specs/two.ts [7ms]
-# 🚀 specs/three.yaml -> schemas/specs/three.ts [7ms]
+# 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [250ms]
 ```
 
-_Thanks, [@sharmarajdaksh](https://github.com/sharmarajdaksh)!_
+### Multiple schemas
 
-### Remote schemas
+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`:
+
+```yaml
+apis:
+  core@v2:
+    root: ./openapi/openapi.yaml
+    openapi-ts:
+      output: ./openapi/openapi.ts
+  external@v1:
+    root: ./openapi/external.yaml
+    openapi-ts:
+      output: ./openapi/openapi.ts
+```
+
+Whenver you have a `redocly.yaml` file in your project with `apis`, you can omit the input/output parameters in the CLI:
 
 ```bash
-npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml -o petstore.d.ts
+npx openapi-typescript
+```
 
-# 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [250ms]
+> ⚠️ 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.
+
+## Redoc config
+
+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:
+
+```bash
+npx openapi-typescript --redoc ./path/to/redocly.yaml
+```
+
+You can read more about the Redoc’s configuration options [in their docs](https://redocly.com/docs/cli/configuration/).
+
+## Auth
+
+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:
+
+```yaml
+resolve:
+  http:
+    headers:
+      - matches: https://api.example.com/v2/**
+        name: X-API-KEY
+        envVariable: SECRET_KEY
+      - matches: https://example.com/*/test.yaml
+        name: Authorization
+        envVariable: SECRET_AUTH
 ```
 
-_Thanks, [@psmyrdek](https://github.com/psmyrdek)!_
+Refer to the [Redocly docs](https://redocly.com/docs/cli/configuration/#resolve-non-public-or-non-remote-urls) for additional options.
 
 ## Options
 
-| Option                    | Alias | Default  | Description                                                                                                                  |
-| :------------------------ | :---- | :------: | :--------------------------------------------------------------------------------------------------------------------------- |
-| `--help`                  |       |          | Display inline help message and exit                                                                                         |
-| `--version`               |       |          | Display this library’s version and exit                                                                                      |
-| `--output [location]`     | `-o`  | (stdout) | Where should the output file be saved?                                                                                       |
-| `--auth [token]`          |       |          | Provide an auth token to be passed along in the request (only if accessing a private schema)                                 |
-| `--header`                | `-x`  |          | Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the `key: value` pattern |
-| `--headers-object="{…}"`  | `-h`  |          | Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over `--header`           |
-| `--http-method`           | `-m`  |  `GET`   | Provide the HTTP Verb/Method for fetching a schema from a remote URL                                                         |
-| `--immutable-types`       |       | `false`  | Generates immutable types (readonly properties and readonly array)                                                           |
-| `--additional-properties` |       | `false`  | Allow arbitrary properties for all schema objects without `additionalProperties: false`                                      |
-| `--empty-objects-unknown` |       | `false`  | Allow arbitrary properties for schema objects with no specified properties, and no specified `additionalProperties`          |
-| `--default-non-nullable`  |       | `false`  | Treat schema objects with default values as non-nullable                                                                     |
-| `--export-type`           | `-t`  | `false`  | Export `type` instead of `interface`                                                                                         |
-| `--path-params-as-types`  |       | `false`  | Allow dynamic string lookups on the `paths` object                                                                           |
-| `--support-array-length`  |       | `false`  | Generate tuples using array `minItems` / `maxItems`                                                                          |
-| `--alphabetize`           |       | `false`  | Sort types alphabetically                                                                                                    |
-| `--exclude-deprecated`    |       | `false`  | Exclude deprecated fields from types                                                                                         |
-
-### `--path-params-as-types`
+| Option                    | Alias | Default  | Description                                                                                                         |
+| :------------------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------------ |
+| `--help`                  |       |          | Display inline help message and exit                                                                                |
+| `--version`               |       |          | Display this library’s version and exit                                                                             |
+| `--output [location]`     | `-o`  | (stdout) | Where should the output file be saved?                                                                              |
+| `--redoc [location]`      |       |          | Path to a `redocly.yaml` file (see [Multiple schemas](#multiple-schemas))                                           |
+| `--immutable`             |       | `false`  | Generates immutable types (readonly properties and readonly array)                                                  |
+| `--additional-properties` |       | `false`  | Allow arbitrary properties for all schema objects without `additionalProperties: false`                             |
+| `--empty-objects-unknown` |       | `false`  | Allow arbitrary properties for schema objects with no specified properties, and no specified `additionalProperties` |
+| `--default-non-nullable`  |       | `false`  | Treat schema objects with default values as non-nullable                                                            |
+| `--export-type`           | `-t`  | `false`  | Export `type` instead of `interface`                                                                                |
+| `--path-params-as-types`  |       | `false`  | Allow dynamic string lookups on the `paths` object                                                                  |
+| `--array-length`          |       | `false`  | Generate tuples using array `minItems` / `maxItems`                                                                 |
+| `--alphabetize`           |       | `false`  | Sort types alphabetically                                                                                           |
+| `--exclude-deprecated`    |       | `false`  | Exclude deprecated fields from types                                                                                |
+
+### pathParamsAsTypes flag
 
 By default, your URLs are preserved exactly as-written in your schema:
 
@@ -88,7 +125,7 @@ Though this is a contrived example, you could use this feature to automatically
 
 _Thanks, [@Powell-v2](https://github.com/Powell-v2)!_
 
-### `--support-array-length`
+### arrayLength flag
 
 This option is useful for generating tuples if an array type specifies `minItems` or `maxItems`.
 
@@ -105,7 +142,7 @@ components:
       maxItems: 2
 ```
 
-Enabling `--support-array-length` would change the typing like so:
+Enabling `--array-length` would change the typing like so:
 
 ```diff
   export interface components {

diff --git a/docs/src/content/docs/introduction.md b/docs/src/content/docs/introduction.md
@@ -34,7 +34,7 @@ npm i -D openapi-typescript
 
 ## Basic usage
 
-First, generate a local type file by running `npx openapi-typescript`:
+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:
 
 ```bash
 # Local schema
@@ -46,9 +46,7 @@ npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/sch
 # 🚀 https://myapi.dev/api/v1/openapi.yaml -> ./path/to/my/schema.d.ts [250ms]
 ```
 
-> ⚠️ Be sure to <a href="https://redocly.com/docs/cli/commands/lint/" target="_blank" rel="noopener noreferrer">validate your schemas</a>! openapi-typescript will err on invalid schemas.
-
-Then, import schemas from the generated file like so:
+Then in your TypeScript project, import types where needed:
 
 ```ts
 import { paths, components } from "./path/to/my/schema"; // <- generated by openapi-typescript
@@ -60,8 +58,10 @@ type MyType = components["schemas"]["MyType"];
 type EndpointParams = paths["/my/endpoint"]["parameters"];
 
 // Response obj
-type SuccessResponse = paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"]["schema"];
-type ErrorResponse = paths["/my/endpoint"]["get"]["responses"][500]["content"]["application/json"]["schema"];
+type SuccessResponse =
+  paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"]["schema"];
+type ErrorResponse =
+  paths["/my/endpoint"]["get"]["responses"][500]["content"]["application/json"]["schema"];
 ```
 
 From here, you can use these types for any of the following (but not limited to):