Add express-openapi types

[erikjuhani]

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 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:

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: https://github.com/wesleytodd/express-openapi/issues/25#issuecomment-2309444521

[socket-security[bot]]

New dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher
npm/@types/[email protected]	None	+11	2.4 MB	types
npm/@types/[email protected]	None	0	16.1 kB	types

View full report↗︎

[wesleytodd]

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.

[erikjuhani]

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 dependencies and not under devDependencies as these are consumer facing types. I'll make a quick change to that.

[erikjuhani]

Also I realised that there's a slight mishap in this PR. I think the new dependencies should be defined under dependencies and not under devDependencies as these are consumer facing types. I'll make a quick change to that.

Changed the type dependencies to be under dependencies.

[erikjuhani]

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.

[henry232323]

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.

[wesleytodd]

And @henry232323, unfortunately changes to path-to-regexp broke this lib in both express@>=4.20.0 and express@5. I am going to be working on fixes for that soon.