docs: add roadmap / release notes

integration-tests/typescript-fetch/src/generate-release-notes.ts

@@ -0,0 +1,76 @@
+import * as fs from "node:fs"
+import path from "node:path"
+import {
+  GitHubV3RestApi,
+  GitHubV3RestApiServers,
+} from "./generated/api.github.com.yaml/client"
+
+function formatDate(dateStr: string | null) {
+  if (!dateStr) return ""
+  return new Date(dateStr).toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  })
+}
+
+export async function generateReleaseNotes() {
+  const client = new GitHubV3RestApi({
+    basePath: GitHubV3RestApiServers.default(),
+    defaultHeaders: {},
+  })
+
+  const res = await client.reposListReleases({
+    owner: "mnahkies",
+    repo: "openapi-code-generator",
+    perPage: 100,
+  })
+
+  if (res.status === 200) {
+    const body = await res.json()
+
+    return body.map(
+      (it) => `### ${formatDate(it.published_at)} (${it.name})
+${it.body
+  ?.split("\n")
+  .filter((it) => it.startsWith("#") === false)
+  .join("\n")}
+    `,
+    )
+  }
+
+  throw new Error("failed to fetch releases", {
+    cause: new Error(await res.text()),
+  })
+}
+
+async function main() {
+  const notes = await generateReleaseNotes()
+  const result = `import { Callout, Steps } from 'nextra/components'
+
+# Release notes
+
+<Callout emoji="💡">
+  This page is statically generated from the [Github releases](https://github.com/mnahkies/openapi-code-generator/releases),
+  and may sometimes be slightly out of date.
+</Callout>
+
+<Steps>
+${notes.join("\n")}
+</Steps>
+`
+
+  fs.writeFileSync(
+    path.resolve(
+      __dirname,
+      "../../../packages/documentation/src/pages/reference/release-notes.mdx",
+    ),
+    result.replace(/\r\n/g, "\n"),
+    "utf-8",
+  )
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

packages/documentation/src/pages/overview/_meta.tsx

@@ -0,0 +1,6 @@
+export default {
+  about: "About",
+  "schema-first-design": "Schema-first design",
+  compatibility: "Compatibility",
+  roadmap: "Roadmap",
+}

packages/documentation/src/pages/overview/about.mdx

@@ -7,13 +7,13 @@ and API server scaffolding (routing, validation, serialization) from OpenAPI 3 s
 
 Currently, [OpenAPI 3.0](https://swagger.io/specification/v3), [OpenAPI 3.1](https://swagger.io/specification/), and [TypeSpec](https://typespec.io/) are supported an input specifications.
 
-This gives you amazing auto-complete, and compile-time safety. Typescripts expressive type system it used to
-make the generated clients feel idomatic, and as close to handwritten as possible.
+This gives you amazing auto-complete, and compile-time safety. Typescript's expressive type system is used to
+make the generated clients feel idiomatic, and as close to handwritten as possible.
 
 ![Github API Example](/example.png)
 
 <Callout type="info">
-  Already know that code generation will save you time? Jump straight in with the [quick start guide](../getting-started/quick-start)
+  Already know that code generation will save you time? Jump straight in with the **[quick start guide](../getting-started/quick-start)**
 </Callout>
 
 ### Server Scaffolding Templates
@@ -58,7 +58,7 @@ This project should be considered beta quality, though it's getting close to a v
 It does not yet handle all aspects of the OpenAPI / JSON schema specification, but *most* common
 features are implemented. In particular at the moment __only JSON__ content types are supported properly.
 
-You can get a sense of what works by looking at the [compatibility](./compatibility) tables, or the [Github issues](https://github.com/mnahkies/openapi-code-generator/issues) (non-exhaustive).
+You can get a sense of what works by looking at the [compatibility](./compatibility) tables, or the [roadmap](./roadmap).
 However often the best way is to just try it out with your API specification and see what happens!
 
 The [integration tests](https://github.com/mnahkies/openapi-code-generator/tree/main/integration-tests) also act as a good showcase of the sort of output you can expect.

packages/documentation/src/pages/overview/roadmap.mdx

@@ -0,0 +1,180 @@
+import {Callout, Steps} from "nextra/components"
+
+# Roadmap
+This is a **very** loosely ordered view of known things that are planned in the roadmap. It's probably not exhaustive.
+
+## Near-term - "Sometime in the next 6 months"
+These are broadly speaking the known blockers to doing the first v1 release.
+
+<Callout emoji="💡">
+
+  The project was started [approximately July
+  2020](https://github.com/mnahkies/openapi-code-generator/commit/643a06835bfb6e462fdeb31f5432cac5ef8ef7f5), over 4
+  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.
+
+</Callout>
+
+<Steps>
+  ### Support multipart/form-data (file uploads)
+
+  Currently only `application/json` request bodies are supported properly.
+
+  This is particularly problematic when wanting to upload files, such as images
+  or videos.
+
+  Adding `multipart/form-data` support will aim to solve this.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#considerations-for-file-uploads
+
+  ### Support response headers
+
+  It's common for important metadata, such as rate limit information to be
+  communicated using response headers.
+
+  At the moment this information is lost during code generation, adding support
+  will mean that it is typed and validated at runtime.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#response-object
+
+  ### Support cookie parameters
+
+  Cookies are often used to store small pieces of information to be sent on every
+  request. These are currently ignored, but should be supported.
+
+  ### Review handling of parameter `style`
+
+  Review and improve the way that parameter `style` is interpreted.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#style-values
+
+  ### Fix interpretation of `readOnly` / `writeOnly`
+
+  The meaning of these attributes was incorrectly interpreted and implemented. Changing this will
+  be a breaking change, so this should be revisited prior to v1.
+
+  ### Clean up / rethink CLI options
+
+  As the number of CLI options has grown, it's been a bit confusing around when options are/aren't
+  used, and it's not super clear how languages other than `typescript` might be introduced.
+
+  We should have a rethink of this, and probably separate client sdk vs server stubs in the option
+  structure to make it clear when args are applicable.
+
+  It may be difficult to maintain backwards compatibility, but if possible then we should.
+
+</Steps>
+
+## Mid-term - "Hopefully in the next year"
+These are items that are nice to have, but generally not breaking and therefore not blocking for a v1
+release. There's a decent chance that many of these will beat a v1 release still.
+
+<Steps>
+  ### Implement a `typescript-express` template
+
+  [express](https://www.npmjs.com/package/express) is probably still the most popular
+  web framework for nodejs, with approximately 10x more weekly downloads than `koa`
+
+  It's also pretty similar in design to `koa`, and so it should low-effort to add a
+  template for it.
+
+  This would be beneficial in terms of making the project useful to a wider userbase,
+  but also be a forcing function to tidy up the koa template code, and abstract it in
+  a similar way to the client templates are.
+
+  ### Complete an interactive playground
+
+  Many tools of this genre offer an interactive playground on their documentation sites,
+  to better communicate the tools purpose and features.
+
+  An interactive playground PR has been up for a while, https://github.com/mnahkies/openapi-code-generator/pull/216
+  but it turns out these are hard to build, and it needs some more effort to get over the line.
+
+  ### Support custom serialization/deserialization
+
+  Sometimes you want to serialize or deserialize objects in a custom way. Good examples
+  might be parsing `date-time` strings as a `moment` / `Instant` instead of the native `Date`,
+  or parsing a `uuid` string to a first class `Uuid` type.
+
+  https://github.com/mnahkies/openapi-code-generator/pull/220 starts to explore this idea,
+  and how we could potentially make use of a custom extension to facilitate this use-case.
+
+  ### Implement a `typescript-next` template
+
+  [next.js](https://nextjs.org/) is a popular framework for building site using `react`.
+  An experimental template has been up here https://github.com/mnahkies/openapi-code-generator/pull/152
+  for months, but it needs some effort to really nail the user experience.
+
+  This is coming after an `typescript-express` template, as producing the former will
+  necessitate several important refactorings that will make this easier to achieve.
+
+  ### Explore test framework integrations
+
+  [nock](https://www.npmjs.com/package/nock) is a popular library for mocking http requests
+  in test suites. What would an integration with `nock` look like? Or maybe mock service worker?
+
+  Could we leverage examples to create fixture factories?
+
+  ### Support Security Schemas
+
+  At the moment we ignore security schemas, and expect the user to handle this themselves
+  out of band of the code generation.
+
+  For example by mounting a custom authentication middleware for Koa servers, or passing
+  an `Authorization` header for client SDKs.
+
+  It would be good to investigate how to improve things using declared security schemes.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object-0
+
+</Steps>
+
+## Long-term - "One Day"
+This is a set of possible future enhancements, generally covering more niche/uncommon parts
+of the OpenAPI standard, that we _might_ implement one day.
+
+Whilst these are lower down the list due to being uncommon (often appearing 0 times in the range of
+integration tests we currently run), there's also an argument to be made that unless tooling steps up
+to support these features, then adoption will remain low, and so support should be added regardless.
+
+<Steps>
+
+  ### 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
+  a server might not support JSON.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#xml-object
+
+  ### Support `webhooks`
+  The `webhooks` object is a new way to declare webhooks in 3.1. We should investigate
+  supporting it.
+
+  ref: https://learn.openapis.org/examples/v3.1/webhook-example.html
+
+  ### Support `links`
+
+  The `links` object on responses is an interesting mechanism to declare relationships
+  between operations, and how to traverse these, using a static declaration.
+
+  It essentially allows you to specify a mapping of properties from one request, to be
+  parameters for another request. Eg: `$request.path.id`
+
+  Whilst interesting, it's also uncommon - currently there isn't a single usage of this
+  feature in the specifications we use for our integration tests.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#link-object
+
+  ### Support `callbacks`
+
+  The `callbacks` field of an operation is similar to the `links` response object, in that
+  it provides a way to specify callbacks related to an operation.
+
+  Much like `links`, it's uncommon to see this used in practice, without a single `callbacks`
+  object defined in any specifications we see.
+
+  ref: https://spec.openapis.org/oas/v3.1.1.html#callback-object
+</Steps>

packages/documentation/src/pages/overview/schema-first-design.mdx

@@ -9,6 +9,8 @@ This project being a code generator from API specification files is on the schem
 Ultimately this is fairly subjective, but there are four primary motivators that lead us to believe schema first
 is the better approach.
 
+This is also recommended by the OpenAPI initiative (OAI) itself, where they refer to this as ["Design-first"](https://learn.openapis.org/best-practices.html) with similar arguments
+
 ## Longevity
 [APIs are forever](https://www.allthingsdistributed.com/2016/03/10-lessons-from-10-years-of-aws.html),
 changing them in backwards incompatible ways is hard/expensive, or sometimes not possible.