Add express-openapi types #64
Conversation
|
New dependencies detected. Learn more about Socket for GitHub ↗︎
|
|
Hey, really sorry I left this hanging for so long. We were busy doing the big express release and then I needed to take a bit of time to try and recover. I will get to this soon, but wanted to drop a note in advance to thank you very much for this. |
No worries at all! Take your time, recover and don't take too much pressure from this PR! 🙇 Thanks for letting me know! (BTW, we already upgraded one node project using express 4.x to 5.x — works like a charm!) Also I realised that there's a slight mishap in this PR. I think the new dependencies should be defined under |
This commit includes typing all the public facing signatures. The types
also include API documentation in JSDoc format that is available in the
root README of the repository. Most of the types were deduced by hand
from the source code and tested with actual runtime data to make sure
that the written types match with the runtime data.
The component methods use function overloading to provide better code
completion of the expected parameters and return values. For example
giving a type and a name to `component("examples", "FooExample")`
returns the expected type of `ReferenceObject` conforming to the API
documentation.
Similarly setting the type for the component function affects what it
will return or take as an input. The input parameter and return type
will conform to the expected type. For example:
```ts
const schemas = openapi.component("schemas");
// ^? { [key: string]: SchemaObject | ReferenceObject }
const examples = openapi.component("examples");
// ^? { [key: string]: ExampleObject | ReferenceObject }
```
The types utilize existing types defined in "openapi-types" and most of
the public facing API functions rely on these types.
The initial typings file was derived from the work presented here: wesleytodd#25 (comment)
erikjuhani
force-pushed
the
express-openapi-types
branch
from
901346d
to
7f6336d
Compare
Changed the type dependencies to be under |
|
Tests are breaking, but it's unrelated to my package.json change and I believe it's caused by the new minor version releases in express. |
|
I'm getting the following error when attempting to run this on Express v5. This seems to be a regression from v4. TypeError: Cannot read properties of undefined (reading 'fast_slash')
at split (/path/to/project/node_modules/@wesleytodd/openapi/lib/generate-doc.js:127:20)
at /path/to/project/node_modules/@wesleytodd/openapi/lib/generate-doc.js:75:27
at Array.forEach (<anonymous>)
at iterateStack (/path/to/project/node_modules/@wesleytodd/openapi/lib/generate-doc.js:73:24)
at /path/to/project/node_modules/@wesleytodd/openapi/lib/generate-doc.js:17:5
at Array.forEach (<anonymous>)
at generateDocument (/path/to/project/node_modules/@wesleytodd/openapi/lib/generate-doc.js:16:26)
at OpenApiMiddleware (/path/to/project/node_modules/@wesleytodd/openapi/index.js:42:29)
at Layer.handleRequest (/path/to/project/node_modules/express/node_modules/router/lib/layer.js:145:17)
at trimPrefix (/path/to/project/node_modules/express/node_modules/router/index.js:337:13)I can share more code if needed. |
Hey @wesleytodd! 👋
I noticed that you had an open issue #25 for adding typescript types to this library. Fortunately there was already a base to start with, which I used here.
I've tested the types so hopefully they are 1 to 1 match with the runtime data. However there could be some things I missed.
Let me know if you want any changes or clarification!
This commit includes typing all the public facing signatures. The types also include API documentation in JSDoc format that is available in the root README of the repository. Most of the types were deduced by hand from the source code and tested with actual runtime data to make sure that the written types match with the runtime data.
The component methods use function overloading to provide better code completion of the expected parameters and return values. For example giving a type and a name to
component("examples", "FooExample")returns the expected type ofReferenceObjectconforming to the API documentation.Similarly setting the type for the component function affects what it will return or take as an input. The input parameter and return type will conform to the expected type. For example:
The types utilize existing types defined in "openapi-types" and most of the public facing API functions rely on these types.
The initial typings file was derived from the work presented here: #25 (comment)