API Documentation

[jshbrntt]

I would really appreciate some API Docs for this library I've had to go through and read the source in order to know what options can be supplied to the Swagger client factory.

[bestmike007]

@shockey how about adding typescript definition for this module? I wonder if there's someone already working on this.

[shockey]

@bestmike007, I don't know of any efforts to do this, but if it's something that's testable (assert: do the TS definitions match what we're exporting at any given time?) it sounds like a great enhancement 😄

[bestmike007]

I think there are two ways of doing this:

1. Add a TS definition file: need more work to ensure it's consistent with what's exported, and additional tests for that
2. Translate the code into typescript: generated definitions from code, one source of truth, but everything will be changed

I prefer the latter option if it's okay with the team and planned in a new release.

[shockey]

@bestmike007, we aren't in a position to accept a TypeScript rewrite at this time, but a definition file would be great.

We may explore a TS rewrite at a later time.

[cspotcode]

Typescript 3.7 allows generating .d.ts files directly from .js. This means you can annotate your .js with comments to declare types, and tsc can create .d.ts declarations from there.

Then you can gradually port the codebase to .ts proper, which has a better syntax for describing types.

TypeScript 3.7 is currently in beta and a stable release is scheduled for November.

[char0n]

Created first PR that should increase the documentation coverage and quality of our documentation. I've started with a Swagger specification resolver.

[char0n]

Documentation has been consolidated into docs/ directory.

If you wish to provide a TypeScript typings for this library, please create a separate issue for that.