Add Swagger UI endpoint

[perfectra1n]

Currently it's just /api-docs...but I'm open to changing it since that's not the "best looking" endpoint lol

Got the idea from #1123.

[eliandoran]

What about on GET /etapi/?

[pano9000]

General observations:

• that seems to be bringing in quite a big dependecy: 11 MB for https://www.npmjs.com/package/swagger-ui-dist for displaying swagger
• the swagger-ui-express would be able to load .json file directly, without an extra js-yaml dependency:
  • maybe it's worth it to convert the yaml file to JSON? Not sure, just a thought
• I would avoid using readFileSync and instead use the async version via fs/promises

edit:
alternative idea would be to link to https://editor.swagger.io/, but that would of course come with some downsides as well (i.e. you would need to rely on a external service again).

[perfectra1n]

that seems to be bringing in quite a big dependecy: 11 MB for https://www.npmjs.com/package/swagger-ui-dist for displaying swagger

Yeah, the Swagger UI will increase the packages size but does offer quite a bit of functionality as a tradeoff.

the swagger-ui-express would be able to load .json file directly, without an extra js-yaml dependency: maybe it's worth it to convert the yaml file to JSON? Not sure, just a thought

I'm open to converting the YAML OpenAPI file to JSON, but I have found it more commonly stored as a YAML format. Maybe there's another package I can use to load it without adding another dep.

I would avoid using readFileSync and instead use the async version via fs/promises

Sure, I can change that!

[pano9000]

I'm open to converting the YAML OpenAPI file to JSON, but I have found it more commonly stored as a YAML format. Maybe there's another package I can use to load it without adding another dep.

don't worry about it, it probably isn't worth investigating it, it was just something that popped up, while reading it.
I agree, that in 95% of the cases, you will find the file in yaml format, and it does look a tiny bit weird looking at the converted file in JSON format :-D

[perfectra1n]

Yeah, we would need the js-yaml package to load the YAML into Swagger UI. I've gone ahead and changed the Site Title as well to match what Elian suggested.

[pano9000]

bit of a nitpicking comment:

the swaggerUI types seem to suggest that it takes a JsonObject type
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/84e6da3397915d415adf7ef5b636affd8638b447/types/swagger-ui-express/index.d.ts#L38

the js-yaml types suggest that "load" returns an unknown type
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/84e6da3397915d415adf7ef5b636affd8638b447/types/js-yaml/index.d.ts#L3

So I think if we do a typecast here, it should be OK to typecast this to "JsonObject" instead.

what do you think?

(you might need to use import type to import the definition)

[pano9000]

that last commit was more about making the TypeScript gods not flinch, when they see that typecasting ;-)

it looks good for me now, thank you (and sorry for nitpicking ;-))
I will leave it up to @eliandoran to decide if he want to also include Swagger UI built in or not :-)

[eliandoran]

It's fine for now, however in the future I would hope to generate the documentation statically and serve that instead if it reduces the binary size.