From 95ce03dc44eafd503f66cddded2caf4226cb0400 Mon Sep 17 00:00:00 2001 From: Michael Nahkies Date: Sat, 30 May 2026 14:01:21 +0100 Subject: [PATCH 1/3] docs: minor improvements --- README.md | 2 +- .../app/getting-started/quick-start/page.mdx | 4 ++-- .../src/app/guides/concepts/enums/page.mdx | 2 +- .../typescript-express/page.mdx | 2 +- .../server-templates/typescript-koa/page.mdx | 2 +- packages/documentation/src/app/layout.tsx | 22 ++++++++++++++----- packages/documentation/src/app/not-found.mdx | 4 ++++ .../src/app/overview/about/page.mdx | 8 +++---- .../src/app/overview/compatibility/page.mdx | 16 ++++++++++---- .../src/app/overview/roadmap/page.mdx | 9 ++------ .../src/app/reference/cli-options/page.mdx | 2 +- packages/documentation/src/globals.d.ts | 7 ++++++ .../src/lib/not-found-tracker.tsx | 12 ++++++++++ packages/documentation/src/lib/track.ts | 5 +++++ 14 files changed, 70 insertions(+), 27 deletions(-) create mode 100644 packages/documentation/src/globals.d.ts create mode 100644 packages/documentation/src/lib/not-found-tracker.tsx create mode 100644 packages/documentation/src/lib/track.ts diff --git a/README.md b/README.md index 9895f2543..8f0d0b6b9 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![CI/CD](https://github.com/mnahkies/openapi-code-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/mnahkies/openapi-code-generator/actions?query=branch%3Amain+event%3Apush) [![npm](https://img.shields.io/npm/v/@nahkies/openapi-code-generator.svg)](https://www.npmjs.com/package/@nahkies/openapi-code-generator) -`@nahkies/openapi-code-generator` is a CLI tool that aims to generate high quality typescript client SDK's, +`@nahkies/openapi-code-generator` is a CLI tool that aims to generate high quality typescript client SDKs, and API server scaffolding (routing, validation, serialization) from api specifications. Currently, [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4.html), [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.1.html), diff --git a/packages/documentation/src/app/getting-started/quick-start/page.mdx b/packages/documentation/src/app/getting-started/quick-start/page.mdx index a5f51aa91..36d91fa2c 100644 --- a/packages/documentation/src/app/getting-started/quick-start/page.mdx +++ b/packages/documentation/src/app/getting-started/quick-start/page.mdx @@ -111,7 +111,7 @@ You can check the version we develop and test against [here](https://github.com/ By default the runtime validation is using `zod@^4`, though you can also use `zod@^3`, or `joi` - See [Guide to typescript-koa client template](/guides/server-templates/typescript-koa) for more details. + See [Guide to typescript-koa server template](/guides/server-templates/typescript-koa) for more details. @@ -144,7 +144,7 @@ You can check the version we develop and test against [here](https://github.com/ By default the runtime validation is using `zod@^4`, though you can also use `zod@^3`, or `joi` - See [Guide to typescript-express client template](/guides/server-templates/typescript-express) for more details. + See [Guide to typescript-express server template](/guides/server-templates/typescript-express) for more details. diff --git a/packages/documentation/src/app/guides/concepts/enums/page.mdx b/packages/documentation/src/app/guides/concepts/enums/page.mdx index 3f54b957f..44b5fc503 100644 --- a/packages/documentation/src/app/guides/concepts/enums/page.mdx +++ b/packages/documentation/src/app/guides/concepts/enums/page.mdx @@ -180,5 +180,5 @@ enum: Currently all `enum` handling for our `typescript` templates use [union types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types), rather than actual [enum](https://www.typescriptlang.org/docs/handbook/enums.html) statements. -This is mostly a stylistic choice, based on the authors personal preferences and subjective opinions of ergonomics. It's +This is mostly a stylistic choice, based on the author's personal preferences and subjective opinions of ergonomics. It's possible that an option to output "real" enums may be added in the future. diff --git a/packages/documentation/src/app/guides/server-templates/typescript-express/page.mdx b/packages/documentation/src/app/guides/server-templates/typescript-express/page.mdx index a2e7e4c35..b88663086 100644 --- a/packages/documentation/src/app/guides/server-templates/typescript-express/page.mdx +++ b/packages/documentation/src/app/guides/server-templates/typescript-express/page.mdx @@ -237,5 +237,5 @@ const getProfileImage: GetProfileImage = async ({body}, respond, req, res, next) } ``` -It should be seldom that these escape hatches are required, and overtime fewer and fewer situations will +It should be seldom that these escape hatches are required, and over time fewer and fewer situations will require them. diff --git a/packages/documentation/src/app/guides/server-templates/typescript-koa/page.mdx b/packages/documentation/src/app/guides/server-templates/typescript-koa/page.mdx index 0d846e76c..0b9f8a098 100644 --- a/packages/documentation/src/app/guides/server-templates/typescript-koa/page.mdx +++ b/packages/documentation/src/app/guides/server-templates/typescript-koa/page.mdx @@ -236,5 +236,5 @@ const getProfileImage: GetProfileImage = async ({body}, respond, ctx, next) => { } ``` -It should be seldom that these escape hatches are required, and overtime fewer and fewer situations will +It should be seldom that these escape hatches are required, and over time fewer and fewer situations will require them. diff --git a/packages/documentation/src/app/layout.tsx b/packages/documentation/src/app/layout.tsx index fdc87084d..c4ae54754 100644 --- a/packages/documentation/src/app/layout.tsx +++ b/packages/documentation/src/app/layout.tsx @@ -81,12 +81,24 @@ export default async function RootLayout({children}: {children: ReactNode}) { diff --git a/packages/documentation/src/app/overview/about/page.mdx b/packages/documentation/src/app/overview/about/page.mdx index bc0c93672..dcda3cbf4 100644 --- a/packages/documentation/src/app/overview/about/page.mdx +++ b/packages/documentation/src/app/overview/about/page.mdx @@ -7,7 +7,7 @@ import {Callout} from "nextra/components" # Welcome -`@nahkies/openapi-code-generator` is a CLI tool that aims to generate high quality typescript client SDK's, +`@nahkies/openapi-code-generator` is a CLI tool that aims to generate high quality typescript client SDKs, and API server scaffolding (routing, validation, serialization) from OpenAPI 3 specifications. Currently, [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4.html), [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.1.html), and [TypeSpec](https://typespec.io/) are supported input specifications. @@ -42,7 +42,7 @@ never misspell a field name or route again. - [typescript-angular](../guides/client-templates/typescript-angular) -## Project Goal / Principals +## Project Goal / Principles To make it fun, easy, and productive to generate both client and server "glue" code from openapi 3 definitions. This is code that is tedious and error-prone to maintain by hand, by automating it we can **reduce toil and frustration**. @@ -51,9 +51,9 @@ The generated code **output should be "stable"** in the sense that it will not arbitrarily change between generation without need (for a given version). For example outputting entities in alphabetic order where possible. -It should also be **generated in a way that human would reasonably write it**, +It should also be **generated in a way that a human would reasonably write it**, the intent is that the generated code can and should be committed to the consuming project -repositories, allowing it to be reviewed, and audited overtime. +repositories, allowing it to be reviewed and audited over time. This is particularly useful in the case of mistakes in the generation or schemas, and also serves to reduce risk of adoption. **There should be no lock-in** - if you wish to stop using the diff --git a/packages/documentation/src/app/overview/compatibility/page.mdx b/packages/documentation/src/app/overview/compatibility/page.mdx index 38e8f769b..8f3059610 100644 --- a/packages/documentation/src/app/overview/compatibility/page.mdx +++ b/packages/documentation/src/app/overview/compatibility/page.mdx @@ -183,10 +183,13 @@ everything should just work as you'd guess/expect. | content | 🚫 | Not yet supported | ### Request Body Object -Well-supported for `application/json` (including some variations like `application/scim+json`), `text/plain`, -and `application/x-www-form-urlencoded` content types, +Well-supported for: +- `application/json` (including some variations like `application/scim+json`) +- `text/plain` / `text/x-markdown` (plain `string`) +- `application/x-www-form-urlencoded` (`URLSearchParams`) +- `application/octet-stream` (`Blob`) -Support for `multipart/form-data`, `application/octocat-stream`, etc. planned to come soon. +Support for `multipart/form-data`, etc. planned to come soon. | Attribute | Supported | Notes | |:------------------------------|:---------:|---------------------------------------------------------------:| @@ -212,8 +215,13 @@ Well supported. | [`{http-status-code}`](#response-object) | ✅ | | ### Response Object -Generally well-supported for `application/json` content types. +Well-supported for: +- `application/json` (including some variations like `application/scim+json`) +- `text/plain` / `text/x-markdown` (plain `string`) +- `application/x-www-form-urlencoded` (`URLSearchParams`) +- `application/octet-stream` (`Blob`) +Support for `multipart/form-data`, etc. planned to come soon. | Attribute | Supported | Notes | |:------------------------------|:---------:|:----------------------------------------------------| | description | __N/A__ | Ignored | diff --git a/packages/documentation/src/app/overview/roadmap/page.mdx b/packages/documentation/src/app/overview/roadmap/page.mdx index 88ecbffc7..c35285340 100644 --- a/packages/documentation/src/app/overview/roadmap/page.mdx +++ b/packages/documentation/src/app/overview/roadmap/page.mdx @@ -12,14 +12,9 @@ This is a **very** loosely ordered view of known things that are planned in the These are broadly speaking the known blockers to doing the first v1 release. - The project was started [approximately July - 2020](https://github.com/mnahkies/openapi-code-generator/commit/643a06835bfb6e462fdeb31f5432cac5ef8ef7f5), over 4 + 2020](https://github.com/mnahkies/openapi-code-generator/commit/643a06835bfb6e462fdeb31f5432cac5ef8ef7f5), over 5 years ago. - - It'd be really nice to get to a v1 / stable release before it turns 5 years old 😅, so we'll aim for this to happen - approximately Q1/Q2 of 2025. - @@ -130,7 +125,7 @@ to support these features, then adoption will remain low, and so support should ### Support XML Whilst JSON has broadly gained popularity over XML as a markup for HTTP requests, - XML isn't dead. It would be good to support it, especially for client SDK's where + XML isn't dead. It would be good to support it, especially for client SDKs where a server might not support JSON. ref: https://spec.openapis.org/oas/v3.1.1.html#xml-object diff --git a/packages/documentation/src/app/reference/cli-options/page.mdx b/packages/documentation/src/app/reference/cli-options/page.mdx index d62eebb22..fe362daf5 100644 --- a/packages/documentation/src/app/reference/cli-options/page.mdx +++ b/packages/documentation/src/app/reference/cli-options/page.mdx @@ -31,7 +31,7 @@ supplied instead. #### `-o --output ` As environment variable `OPENAPI_OUTPUT` -directory to output generated code (env: ) +The directory to output generated code. Eg: `./src/generated/` #### `-t --template ` As environment variable `OPENAPI_TEMPLATE` diff --git a/packages/documentation/src/globals.d.ts b/packages/documentation/src/globals.d.ts new file mode 100644 index 000000000..359a6d54c --- /dev/null +++ b/packages/documentation/src/globals.d.ts @@ -0,0 +1,7 @@ +export {} + +declare global { + interface Window { + plausible: any + } +} diff --git a/packages/documentation/src/lib/not-found-tracker.tsx b/packages/documentation/src/lib/not-found-tracker.tsx new file mode 100644 index 000000000..4f183780d --- /dev/null +++ b/packages/documentation/src/lib/not-found-tracker.tsx @@ -0,0 +1,12 @@ +import {useEffect} from "react" +import {track} from "./track" + +export function NotFoundTracker() { + useEffect(() => { + track("404") + }, []) + + return null +} + +export default NotFoundTracker diff --git a/packages/documentation/src/lib/track.ts b/packages/documentation/src/lib/track.ts new file mode 100644 index 000000000..89fc7f447 --- /dev/null +++ b/packages/documentation/src/lib/track.ts @@ -0,0 +1,5 @@ +export function track(event: string, props?: Record) { + if (typeof window !== "undefined" && window.plausible) { + window.plausible(event, {props}) + } +} From 8a682a22863fc82a500245adbc00710b9418221a Mon Sep 17 00:00:00 2001 From: Michael Nahkies Date: Sat, 30 May 2026 21:16:38 +0100 Subject: [PATCH 2/3] fix: use client --- packages/documentation/src/lib/not-found-tracker.tsx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/documentation/src/lib/not-found-tracker.tsx b/packages/documentation/src/lib/not-found-tracker.tsx index 4f183780d..d32933646 100644 --- a/packages/documentation/src/lib/not-found-tracker.tsx +++ b/packages/documentation/src/lib/not-found-tracker.tsx @@ -1,3 +1,5 @@ +"use client" + import {useEffect} from "react" import {track} from "./track" From 125f01efe74b2e7be34acc7b3b5c38862fd789f2 Mon Sep 17 00:00:00 2001 From: Michael Nahkies Date: Sun, 31 May 2026 09:48:35 +0100 Subject: [PATCH 3/3] fix: use client --- packages/documentation/src/app/layout.tsx | 23 ++------------- .../src/lib/plausible-script.tsx | 28 +++++++++++++++++++ 2 files changed, 30 insertions(+), 21 deletions(-) create mode 100644 packages/documentation/src/lib/plausible-script.tsx diff --git a/packages/documentation/src/app/layout.tsx b/packages/documentation/src/app/layout.tsx index c4ae54754..1f71cc54f 100644 --- a/packages/documentation/src/app/layout.tsx +++ b/packages/documentation/src/app/layout.tsx @@ -3,8 +3,8 @@ import {getPageMap} from "nextra/page-map" import {Footer, Layout, Link, Navbar} from "nextra-theme-docs" import "nextra-theme-docs/style.css" import type {Metadata} from "next" -import Script from "next/script" import type {ReactNode} from "react" +import PlausibleScript from "../lib/plausible-script" export const metadata: Metadata = { title: { @@ -79,26 +79,7 @@ export default async function RootLayout({children}: {children: ReactNode}) { -