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.
The project was started approximately July 2020, 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.
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.
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.
Implement a typescript-express template
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 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 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
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.
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