Add api schemas and swagger ui support

[knolleary]

Part of #1556

Raised as a Draft to get some early feedback on the general approach.

Description

This adds the initial Swagger UI and adds schemas to the authentication, user and teams routes.

• The Swagger doc is served from /api/json
• The Swagger UI is browsable (without authentication) at /api/ (the trailing slash is required... may tidy that up)

This starts to rework how the forge/db/views are defined - so that we can define view schemas alongside the code that creates them. The ultimate goal will be to allow fastify do more work using the schema, but that is out of scope for this work.

I've removed app.db.views.User.shortProfile and replaced it with the existing app.db.views.User.userSummary - trying to maximise view reuse.

---

In terms of testing, this doesn't add any new testable functionality other than the Swagger generation. The main risk is it results in a field being stripped from a response that was previously there, and it's an edge case not covered by the existing tests. I'm doing various bits of UI click testing in addition to exercise the routes as well.

Note that the changes in #2349 will need taking into account as well once that is reviewed and merged.

---

API Files updated (under forge/routes/api):

• admin.js (Add schemas to admin/settings/stack routes #2370)
• application.js (this pr)
• device.js (Add schemas to device api routes #2357)
• deviceLive.js - used by devices to communicate with the platform. Not an external API, so lower priority to document here
• project.js (Add schemas to all /project/ routes #2356)
• projectActions.js (Add schemas to all /project/ routes #2356)
• projectDevices.js (Add schemas to all /project/ routes #2356)
• projectSnapshots.js (Add schemas to all /project/ routes #2356)
• projectType.js (Add schemas to Template, Types and UserInvitation routes #2369)
• settings.js (Add schemas to admin/settings/stack routes #2370)
• stack.js (Add schemas to admin/settings/stack routes #2370)
• team.js (this pr)
• teamDevices.js (Add schemas to all teamDevices routes #2366)
• teamInvitations.js (this pr)
• teamMembers.js (this pr)
• teamType.js (this pr)
• template.js (Add schemas to Template, Types and UserInvitation routes #2369)
• user.js (this pr)
• userInvitations.js (Add schemas to Template, Types and UserInvitation routes #2369)
• users.js (this pr)

[knolleary]

Looks like I've tripped over failing to update package-log.json...

[Pezmc]

@knolleary Let's frame it as you tested the validation was working!

[knolleary]

Final update - have removed the 'Try it out' button from swagger ui as the auth side is a bit funky at this stage.

Also hidden all of the non-api 'authentication' routes.

Finally, figured out how to order the tags so have done so.

@Pezmc all good to review (although you have done most of it via the child-PRs)

[knolleary]

Oh - one more thing... worked out how to document the auth schemes for the routes, but the swagger UI experience isn't ideal IMHO. So have left it in place, but commented out as it isn't entirely obvious to figure out.

[Pezmc]

Yes, realistically I'm not able to go through this with a fine comb, so have tested locally and given a quick skim over.