Merge branch 'drwpow:main' into main

.github/workflows/ci.yml

@@ -17,26 +17,26 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
-      - uses: pnpm/action-setup@v2
+          node-version: 22
+      - uses: pnpm/action-setup@v4
         with:
           version: latest
-      - run: pnpm i
+          run_install: true
       - run: pnpm run lint
   test-node-versions:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 21.x]
+        node-version: [18, 20, 22]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-      - uses: pnpm/action-setup@v2
+      - uses: pnpm/action-setup@v4
         with:
           version: latest
-      - run: pnpm i
+          run_install: true
       - run: pnpm run build
       - run: pnpm test
   test-macos:
@@ -45,27 +45,23 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
-      - uses: pnpm/action-setup@v2
+          node-version: 22
+      - uses: pnpm/action-setup@v4
         with:
           version: latest
-      - run: pnpm i
+          run_install: true
       - run: pnpm run build
       - run: pnpm test
-        env:
-          CI_ENV: macos
   test-windows:
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
-      - uses: pnpm/action-setup@v2
+          node-version: 22
+      - uses: pnpm/action-setup@v4
         with:
           version: latest
-      - run: pnpm i
+          run_install: true
       - run: pnpm run build
       - run: pnpm test
-        env:
-          CI_ENV: windows

.github/workflows/release.yml

@@ -12,11 +12,11 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
-      - uses: pnpm/action-setup@v2
+          node-version: 22
+      - uses: pnpm/action-setup@v4
         with:
           version: latest
-      - run: pnpm i
+          run_install: true
       - run: pnpm run build
       - uses: changesets/action@v1
         with:

docs/.vitepress/shared.ts

@@ -15,11 +15,10 @@ export const shared = defineConfig({
       {
         defer: "",
         src: "https://static.cloudflareinsights.com/beacon.min.js",
-        "data-cf-beacon": '{"token": "f5713e86f9aa43278151f2763d6b59ae"}',
+        "data-cf-beacon": '{"token": "ea4189cb68024071a5aff8663b3b63f1"}',
       },
     ],
   ],
-
   sitemap: {
     hostname: HOSTNAME,
   },
@@ -35,8 +34,6 @@ export const shared = defineConfig({
         locales: { ...zhSearch },
       },
     },
-    socialLinks: [
-      { icon: "github", link: "https://github.com/drwpow/openapi-typescript" },
-    ],
+    socialLinks: [{ icon: "github", link: "https://github.com/drwpow/openapi-typescript" }],
   },
 });

docs/6.x/advanced.md

@@ -85,9 +85,9 @@ And the magic that produces this would live in a `test/utils.ts` file that can b
 <details>
 <summary>📄 <strong>test/utils.ts</strong></summary>
 
-::: code-group [test/utils.ts]
+::: code-group
 
-```ts
+```ts [test/utils.ts]
 import type { paths } from "./api/v1"; // generated by openapi-typescript
 
 // Settings
@@ -123,7 +123,7 @@ export function mockResponses(responses: {
   fetchMock.mockResponse((req) => {
     const mockedPath = findPath(
       req.url.replace(BASE_URL, ""),
-      Object.keys(responses),
+      Object.keys(responses)
     )!;
     // note: we get lazy with the types here, because the inference is bad anyway and this has a `void` return signature. The important bit is the parameter signature.
     if (!mockedPath || (!responses as any)[mockedPath])
@@ -142,11 +142,11 @@ export function mockResponses(responses: {
 // helper function that matches a realistic URL (/users/123) to an OpenAPI path (/users/{user_id}
 export function findPath(
   actual: string,
-  testPaths: string[],
+  testPaths: string[]
 ): string | undefined {
   const url = new URL(
     actual,
-    actual.startsWith("http") ? undefined : "http://testapi.com",
+    actual.startsWith("http") ? undefined : "http://testapi.com"
   );
   const actualParts = url.pathname.split("/");
   for (const p of testPaths) {

docs/advanced.md

@@ -29,7 +29,9 @@ Note that debug messages will be suppressed if the output is `stdout`.
 
 Example:
 
-```yaml
+::: code-group
+
+```yaml [my-openapi-3-schema.yaml]
 ErrorCode:
   type: integer
   format: int32
@@ -47,9 +49,13 @@ ErrorCode:
     - "Something went wrong"
 ```
 
+:::
+
 Will result in:
 
-```ts
+::: code-group
+
+```ts [my-openapi-3-schema.d.ts]
 enum ErrorCode {
   // User is not authorized
   Unauthorized = 100
@@ -60,6 +66,8 @@ enum ErrorCode {
 }
 ```
 
+:::
+
 Alternatively you can use `x-enumNames` and `x-enumDescriptions` ([NSwag/NJsonSchema](https://github.com/RicoSuter/NJsonSchema/wiki/Enums#enum-names-and-descriptions)).
 
 ## Styleguide
@@ -274,7 +282,9 @@ OpenAPI’s composition tools (`oneOf`/`anyOf`/`allOf`) are powerful tools for r
 
 #### ❌ Bad
 
-```yaml
+::: code-group
+
+```yaml [my-openapi-3-schema.yaml]
 Pet:
   type: object
   properties:
@@ -296,19 +306,27 @@ Pet:
     - $ref: "#/components/schemas/Turtle"
 ```
 
+:::
+
 This generates the following type which mixes both TypeScript unions and intersections. While this is valid TypeScript, it’s complex, and inference may not work as you intended. But the biggest offense is TypeScript can’t discriminate via the `type` property:
 
-```ts
+::: code-group
+
+```ts [my-openapi-3-schema.d.ts]
   Pet: ({
     /** @enum {string} */
     type?: "cat" | "dog" | "rabbit" | "snake" | "turtle";
     name?: string;
   }) & (components["schemas"]["Cat"] | components["schemas"]["Dog"] | components["schemas"]["Rabbit"] | components["schemas"]["Snake"] | components["schemas"]["Turtle"]);
 ```
 
+:::
+
 #### ✅ Better
 
-```yaml
+::: code-group
+
+```yaml [my-openapi-3-schema.yaml]
 Pet:
   oneOf:
     - $ref: "#/components/schemas/Cat"
@@ -330,13 +348,19 @@ Cat:
       - cat
 ```
 
+:::
+
 The resulting generated types are not only simpler; TypeScript can now discriminate using `type` (notice `Cat` has `type` with a single enum value of `"cat"`).
 
-```ts
+::: code-group
+
+```ts [my-openapi-3-schema.d.ts]
 Pet: components["schemas"]["Cat"] | components["schemas"]["Dog"] | components["schemas"]["Rabbit"] | components["schemas"]["Snake"] | components["schemas"]["Turtle"];
 Cat: { type?: "cat"; } & components["schemas"]["PetCommonProperties"];
 ```
 
+:::
+
 _Note: you optionally could provide `discriminator.propertyName: "type"` on `Pet` ([docs](https://spec.openapis.org/oas/v3.1.0#discriminator-object)) to automatically generate the `type` key, but is less explicit._
 
 While the schema permits you to use composition in any way you like, it’s good to always take a look at the generated types and see if there’s a simpler way to express your unions & intersections. Limiting the use of `oneOf` is not the only way to do that, but often yields the greatest benefits.
@@ -345,7 +369,9 @@ While the schema permits you to use composition in any way you like, it’s good
 
 [JSONSchema $defs](https://json-schema.org/understanding-json-schema/structuring.html#defs) can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:
 
-```yaml
+::: code-group
+
+```yaml [my-openapi-3-schema.yaml]
 components:
   schemas:
     DefType:
@@ -360,9 +386,13 @@ components:
           $ref: "#/components/schemas/DefType/$defs/myDefType"
 ```
 
+:::
+
 This will transform into the following TypeScript:
 
-```ts
+::: code-group
+
+```ts [my-openapi-3-schema.d.ts]
 export interface components {
   schemas: {
     DefType: {
@@ -377,9 +407,13 @@ export interface components {
 }
 ```
 
+:::
+
 However, this won’t:
 
-```yaml
+::: code-group
+
+```yaml [my-openapi-3-schema.yaml]
 components:
   schemas:
     DefType:
@@ -393,9 +427,13 @@ components:
           $ref: "#/components/schemas/DefType/$defs/myDefType"
 ```
 
+:::
+
 Because it will transform into:
 
-```ts
+::: code-group
+
+```ts [my-openapi-3-schema.d.ts]
 export interface components {
   schemas: {
     DefType: string;
@@ -406,6 +444,8 @@ export interface components {
 }
 ```
 
+:::
+
 So be wary about where you define `$defs` as they may go missing in your final generated types.
 
 ::: tip