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..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,14 +79,7 @@ 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..d32933646 --- /dev/null +++ b/packages/documentation/src/lib/not-found-tracker.tsx @@ -0,0 +1,14 @@ +"use client" + +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/plausible-script.tsx b/packages/documentation/src/lib/plausible-script.tsx new file mode 100644 index 000000000..87e4384b7 --- /dev/null +++ b/packages/documentation/src/lib/plausible-script.tsx @@ -0,0 +1,28 @@ +"use client" + +import Script from "next/script" + +export default function PlausibleScript() { + return ( +