Skip to content

Commit 7177a14

Browse files
mnahkiesmnahkies
authored
docs: add roadmap / release notes (#277)
takes a stab at forming a roadmap, with a view to what's outstanding before the first v1 release, and what's near, mid or long term.
1 parent 3de13c2 commit 7177a14

7 files changed

Lines changed: 734 additions & 4 deletions

File tree

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import * as fs from "node:fs"
2+
import path from "node:path"
3+
import {
4+
GitHubV3RestApi,
5+
GitHubV3RestApiServers,
6+
} from "./generated/api.github.com.yaml/client"
7+
8+
function formatDate(dateStr: string | null) {
9+
if (!dateStr) return ""
10+
return new Date(dateStr).toLocaleDateString("en-GB", {
11+
year: "numeric",
12+
month: "short",
13+
day: "numeric",
14+
})
15+
}
16+
17+
export async function generateReleaseNotes() {
18+
const client = new GitHubV3RestApi({
19+
basePath: GitHubV3RestApiServers.default(),
20+
defaultHeaders: {},
21+
})
22+
23+
const res = await client.reposListReleases({
24+
owner: "mnahkies",
25+
repo: "openapi-code-generator",
26+
perPage: 100,
27+
})
28+
29+
if (res.status === 200) {
30+
const body = await res.json()
31+
32+
return body.map(
33+
(it) => `### ${formatDate(it.published_at)} (${it.name})
34+
${it.body
35+
?.split("\n")
36+
.filter((it) => it.startsWith("#") === false)
37+
.join("\n")}
38+
`,
39+
)
40+
}
41+
42+
throw new Error("failed to fetch releases", {
43+
cause: new Error(await res.text()),
44+
})
45+
}
46+
47+
async function main() {
48+
const notes = await generateReleaseNotes()
49+
const result = `import { Callout, Steps } from 'nextra/components'
50+
51+
# Release notes
52+
53+
<Callout emoji="💡">
54+
This page is statically generated from the [Github releases](https://github.com/mnahkies/openapi-code-generator/releases),
55+
and may sometimes be slightly out of date.
56+
</Callout>
57+
58+
<Steps>
59+
${notes.join("\n")}
60+
</Steps>
61+
`
62+
63+
fs.writeFileSync(
64+
path.resolve(
65+
__dirname,
66+
"../../../packages/documentation/src/pages/reference/release-notes.mdx",
67+
),
68+
result.replace(/\r\n/g, "\n"),
69+
"utf-8",
70+
)
71+
}
72+
73+
main().catch((err) => {
74+
console.error(err)
75+
process.exit(1)
76+
})

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
export default {
2+
about: "About",
3+
"schema-first-design": "Schema-first design",
4+
compatibility: "Compatibility",
5+
roadmap: "Roadmap",
6+
}

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@ and API server scaffolding (routing, validation, serialization) from OpenAPI 3 s
77

88
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.
99

10-
This gives you amazing auto-complete, and compile-time safety. Typescripts expressive type system it used to
11-
make the generated clients feel idomatic, and as close to handwritten as possible.
10+
This gives you amazing auto-complete, and compile-time safety. Typescript's expressive type system is used to
11+
make the generated clients feel idiomatic, and as close to handwritten as possible.
1212

1313
![Github API Example](/example.png)
1414

1515
<Callout type="info">
16-
Already know that code generation will save you time? Jump straight in with the [quick start guide](../getting-started/quick-start)
16+
Already know that code generation will save you time? Jump straight in with the **[quick start guide](../getting-started/quick-start)**
1717
</Callout>
1818

1919
### Server Scaffolding Templates
@@ -58,7 +58,7 @@ This project should be considered beta quality, though it's getting close to a v
5858
It does not yet handle all aspects of the OpenAPI / JSON schema specification, but *most* common
5959
features are implemented. In particular at the moment __only JSON__ content types are supported properly.
6060

61-
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).
61+
You can get a sense of what works by looking at the [compatibility](./compatibility) tables, or the [roadmap](./roadmap).
6262
However often the best way is to just try it out with your API specification and see what happens!
6363

6464
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‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
import {Callout, Steps} from "nextra/components"
2+
3+
# Roadmap
4+
This is a **very** loosely ordered view of known things that are planned in the roadmap. It's probably not exhaustive.
5+
6+
## Near-term - "Sometime in the next 6 months"
7+
These are broadly speaking the known blockers to doing the first v1 release.
8+
9+
<Callout emoji="💡">
10+
11+
The project was started [approximately July
12+
2020](https://github.com/mnahkies/openapi-code-generator/commit/643a06835bfb6e462fdeb31f5432cac5ef8ef7f5), over 4
13+
years ago.
14+
15+
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
16+
approximately Q1/Q2 of 2025.
17+
18+
</Callout>
19+
20+
<Steps>
21+
### Support multipart/form-data (file uploads)
22+
23+
Currently only `application/json` request bodies are supported properly.
24+
25+
This is particularly problematic when wanting to upload files, such as images
26+
or videos.
27+
28+
Adding `multipart/form-data` support will aim to solve this.
29+
30+
ref: https://spec.openapis.org/oas/v3.1.1.html#considerations-for-file-uploads
31+
32+
### Support response headers
33+
34+
It's common for important metadata, such as rate limit information to be
35+
communicated using response headers.
36+
37+
At the moment this information is lost during code generation, adding support
38+
will mean that it is typed and validated at runtime.
39+
40+
ref: https://spec.openapis.org/oas/v3.1.1.html#response-object
41+
42+
### Support cookie parameters
43+
44+
Cookies are often used to store small pieces of information to be sent on every
45+
request. These are currently ignored, but should be supported.
46+
47+
### Review handling of parameter `style`
48+
49+
Review and improve the way that parameter `style` is interpreted.
50+
51+
ref: https://spec.openapis.org/oas/v3.1.1.html#style-values
52+
53+
### Fix interpretation of `readOnly` / `writeOnly`
54+
55+
The meaning of these attributes was incorrectly interpreted and implemented. Changing this will
56+
be a breaking change, so this should be revisited prior to v1.
57+
58+
### Clean up / rethink CLI options
59+
60+
As the number of CLI options has grown, it's been a bit confusing around when options are/aren't
61+
used, and it's not super clear how languages other than `typescript` might be introduced.
62+
63+
We should have a rethink of this, and probably separate client sdk vs server stubs in the option
64+
structure to make it clear when args are applicable.
65+
66+
It may be difficult to maintain backwards compatibility, but if possible then we should.
67+
68+
</Steps>
69+
70+
## Mid-term - "Hopefully in the next year"
71+
These are items that are nice to have, but generally not breaking and therefore not blocking for a v1
72+
release. There's a decent chance that many of these will beat a v1 release still.
73+
74+
<Steps>
75+
### Implement a `typescript-express` template
76+
77+
[express](https://www.npmjs.com/package/express) is probably still the most popular
78+
web framework for nodejs, with approximately 10x more weekly downloads than `koa`
79+
80+
It's also pretty similar in design to `koa`, and so it should low-effort to add a
81+
template for it.
82+
83+
This would be beneficial in terms of making the project useful to a wider userbase,
84+
but also be a forcing function to tidy up the koa template code, and abstract it in
85+
a similar way to the client templates are.
86+
87+
### Complete an interactive playground
88+
89+
Many tools of this genre offer an interactive playground on their documentation sites,
90+
to better communicate the tools purpose and features.
91+
92+
An interactive playground PR has been up for a while, https://github.com/mnahkies/openapi-code-generator/pull/216
93+
but it turns out these are hard to build, and it needs some more effort to get over the line.
94+
95+
### Support custom serialization/deserialization
96+
97+
Sometimes you want to serialize or deserialize objects in a custom way. Good examples
98+
might be parsing `date-time` strings as a `moment` / `Instant` instead of the native `Date`,
99+
or parsing a `uuid` string to a first class `Uuid` type.
100+
101+
https://github.com/mnahkies/openapi-code-generator/pull/220 starts to explore this idea,
102+
and how we could potentially make use of a custom extension to facilitate this use-case.
103+
104+
### Implement a `typescript-next` template
105+
106+
[next.js](https://nextjs.org/) is a popular framework for building site using `react`.
107+
An experimental template has been up here https://github.com/mnahkies/openapi-code-generator/pull/152
108+
for months, but it needs some effort to really nail the user experience.
109+
110+
This is coming after an `typescript-express` template, as producing the former will
111+
necessitate several important refactorings that will make this easier to achieve.
112+
113+
### Explore test framework integrations
114+
115+
[nock](https://www.npmjs.com/package/nock) is a popular library for mocking http requests
116+
in test suites. What would an integration with `nock` look like? Or maybe mock service worker?
117+
118+
Could we leverage examples to create fixture factories?
119+
120+
### Support Security Schemas
121+
122+
At the moment we ignore security schemas, and expect the user to handle this themselves
123+
out of band of the code generation.
124+
125+
For example by mounting a custom authentication middleware for Koa servers, or passing
126+
an `Authorization` header for client SDKs.
127+
128+
It would be good to investigate how to improve things using declared security schemes.
129+
130+
ref: https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object-0
131+
132+
</Steps>
133+
134+
## Long-term - "One Day"
135+
This is a set of possible future enhancements, generally covering more niche/uncommon parts
136+
of the OpenAPI standard, that we _might_ implement one day.
137+
138+
Whilst these are lower down the list due to being uncommon (often appearing 0 times in the range of
139+
integration tests we currently run), there's also an argument to be made that unless tooling steps up
140+
to support these features, then adoption will remain low, and so support should be added regardless.
141+
142+
<Steps>
143+
144+
### Support XML
145+
146+
Whilst JSON has broadly gained popularity over XML as a markup for HTTP requests,
147+
XML isn't dead. It would be good to support it, especially for client SDK's where
148+
a server might not support JSON.
149+
150+
ref: https://spec.openapis.org/oas/v3.1.1.html#xml-object
151+
152+
### Support `webhooks`
153+
The `webhooks` object is a new way to declare webhooks in 3.1. We should investigate
154+
supporting it.
155+
156+
ref: https://learn.openapis.org/examples/v3.1/webhook-example.html
157+
158+
### Support `links`
159+
160+
The `links` object on responses is an interesting mechanism to declare relationships
161+
between operations, and how to traverse these, using a static declaration.
162+
163+
It essentially allows you to specify a mapping of properties from one request, to be
164+
parameters for another request. Eg: `$request.path.id`
165+
166+
Whilst interesting, it's also uncommon - currently there isn't a single usage of this
167+
feature in the specifications we use for our integration tests.
168+
169+
ref: https://spec.openapis.org/oas/v3.1.1.html#link-object
170+
171+
### Support `callbacks`
172+
173+
The `callbacks` field of an operation is similar to the `links` response object, in that
174+
it provides a way to specify callbacks related to an operation.
175+
176+
Much like `links`, it's uncommon to see this used in practice, without a single `callbacks`
177+
object defined in any specifications we see.
178+
179+
ref: https://spec.openapis.org/oas/v3.1.1.html#callback-object
180+
</Steps>

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ This project being a code generator from API specification files is on the schem
99
Ultimately this is fairly subjective, but there are four primary motivators that lead us to believe schema first
1010
is the better approach.
1111

12+
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
13+
1214
## Longevity
1315
[APIs are forever](https://www.allthingsdistributed.com/2016/03/10-lessons-from-10-years-of-aws.html),
1416
changing them in backwards incompatible ways is hard/expensive, or sometimes not possible.

0 commit comments

Comments
 (0)