docs(Swagger API): Implement Swagger for API documentation

[xlisachan]

To view documentation

• Pull down add_hapiswagger branch
• yarn install in fxa-auth-server
• yarn start fxa
• npm start in fxa-auth-server
• Go to localhost:9000/documentation

This pull request

• Adds hapi-swagger@10.3.0 plug-in and dependencies to autogenerate API documentation using Swagger API based on current documentation
• Adds routes that are not in the current API documentation under Miscellaneous - a follow-up ticket has been created to update these routes.
• Adds description (if applicable), labels, notes, plugins (error responses), tags, and other details to routes for the following API endpoints to documentation
  • Account
  • Devices and sessions
  • Emails
  • Oauth
  • Password
  • Recovery codes
  • Recovery key
  • Security events
  • Session
  • Sign
  • Signin codes
  • Sms
  • Subscriptions
  • Totp
  • Unblock codes
  • Util
  • Basic API documentation information (header, descriptions, etc)

Issue that this pull request solves

Closes: #12051

Checklist

Put an x in the boxes that apply

• My commit is GPG signed.
• If applicable, I have modified or added tests which pass locally.
• I have added necessary documentation (if appropriate).
• I have verified that my changes render correctly in RTL (if appropriate).

Screenshots (Optional)

Other information (Optional)

This pull request adds hapi-swagger v10.3.0, as fxa-auth-server is currently utilizing @hapi/joi 15.1.1. Once the entire codebase is using joi v17.x, the following dependencies can be updated:

• hapi/joi[a]15.1.1 -> joi[a]17.6.0
• inert -> [a]hapi/inert
• vision -> [a]hapi/vision

Follow-up tickets filed:

• to have a live URL for public access
• to organize and include additional information for routes within 'Miscellaneous' section
• to update/remove out-of-date information in API documentation
• to add documentation on how to add/modify Swagger details

[LZoog]

@xlisachan sweeeet on updating them to MD😎 That will also address a lot of Peter's "invalid HTML!" comments. I do think we're going to have to use something like dedent for multi-lines which might not look pretty but that's fine. I'd take some of the most complicated pieces (like with code blocks or list items) and try it out there first. There might be a better tool for the job, not sure.

On the separate files, hmmm, I feel like devs would see API_DOCS.ACCOUNT_CREATE_POST.NOTES, or whatever we named those constants, and look up said file, but yeah, maybe it is more clear if it's right there in front of you. Maybe a happy medium could be placing descriptors we reuse across endpoints, like 'Opaque alphanumeric token to be included in verification links.', in a constants object somewhere at least.

I'd definitely be fine with pulling all of the descriptors into individual files like my previous comment happening in a follow up, if we wanted to do it at all, but if we're going to do that I kind of also think it might be less time consuming to do it at the same time you change everything to MD since you'll have to touch almost every string again anyway 😩 Maybe before you start on the refactor to MD, we get one or two opinions on what we deem as ideal here.

[LZoog]

@xlisachan Still looking at this, phew it's a long one but so much nicer with markdown!! 🙌 Here's more thoughts so far:

Sometimes we use the function version of dedent, like

dedent(`

and other times, just

dedent`

I guess if I have to choose I’d pick the latter because less characters but I really don’t mind either way, but can we make that a bit more consistent? 😀

I’m not sure I immediately know the difference between “🔒🔓 sessionToken” and just “🔒sessionToken”. Can we add a key/legend at the top for what the emojis mean?

I still think some sort of constants object could be nice to share common strings, even API headings, but not a must for r+. I could see someone even typoing 'Devices and sessions' and not realizing it because they didn't manually check Swagger.

Questions, please feel free to disagree or push back because I could definitely be missing context or something you found:

• Should /account/finish_setup, /account/lock, /account/sessions/locations and /account/stub go under “Account”? Or /account/sessions/locations under “devices and sessions" depending on how we use it 🤔
• Should some if not all of the /oauth/subscriptions routes go under “Subscriptions” instead of “Miscellaneous”?
• Should /auth/id-token-verify and maybe even authorized-clients endpoints go under oauth?
• Should /recoveryCodes go under “Recovery codes”?
• Should /recoveryKey/verify go under “Recovery key”?

Potential follow up issues:

• I think we can definitely fill in more missing details (not in this PR). account/finish_setup for example, looks to be hit whenever a user resets a password. Do we want to document that kind of thing, or no because it could change later? I’m fine with whatever there, but endpoints like /authorized-clients could use a single sentence descriptor.
• Documentation on how to document, like with tags and notes, using Markdown with dedent etc. Maybe this can be done after we get it out to the public, so we can also document whatever infrastructure we have set up to automatically deploy it
• Move inline validation out of these routes and DRY stuff up along the way, which could help these files feel less cluttered and be better for separation of concerns (maybe chat with @dschom, I stole this idea from him after I getting his input on my suggestion of separating out the docs)

[LZoog]

The account refactor is looking much better separation of concerns wise heh, still feels like I haven't gone through everything but here's a few more comments on your new commit, I might wait before coming back and reviewing again since I didn't realize you were refactoring.

[xlisachan]

Thanks for the feedback, @LZoog!

• I'll comb through as I refactor to ensure I am being consistent in using dedent
• “🔒🔓 sessionToken” vs just “🔒sessionToken” - this is from the current API document, I'll see if I can find a key/legend
• I'll add constants to the route files in the refactor
• Regarding where the routes have been placed in sections - per this PR's description - currently the API doc that Swagger is autogenerating is based on the current API documentation. I'll add that the routes listed under Miscellaneous are routes that were not in the current documentation. I have already filed a follow-up ticket that calls for organizing and adding details to those routes in the Miscellaneous section.
• Potential follow-up issues
  • As mentioned above, there is a follow-up ticket to add the missing details to routes 👍
  • I'll add a follow-up ticket to document how we document (hehe)
  • I think we should have a ticket to clean up the routes where we can as well :) Maintenance sprints FTW!

Question, should removing the current API documentation be included in this ticket?

Thanks again!! :)

[LZoog]

@xlisachan That all sounds great to me! RE: the misc routes, ahh that makes a lot of sense knowing we have #12549.

I've already spent a couple of hours on this today and since you're refactoring I'll probably check back on Friday. It makes sense that anything coming from the existing doc is fine for this PR and we can clean up later.

I think we should have a ticket to clean up the routes where we can as well :) Maintenance sprints FTW!

When you say clean up, do you mean pull out the validation as I mentioned previously in this comment where I @ mentioned Dan, or do you mean add to/review our existing descriptions? I think we could use a documentation review ticket too, for stuff like what's pointed out here. 🙂

Question, should removing the current API documentation be included in this ticket?

Eh, if you've copied and pasted everything from them, I think it's fine to delete them here. If there's more details we might should comb over or if it's going to make the diff significantly larger, it can be done in the doc improvement/review follow up.

[xlisachan]

I meant the first (your comment). 🙃

[xlisachan]

There were some parameters that had two similar descriptions, do we prefer one over the other/want to combine them for a better description?

[LZoog]

@xlisachan Amazing job 👏👏👏 Thanks for tackling this.

Especially after that refactor, things are looking so nice. Almost all of my comments are naming preferences, so those are non-blocking and feel free to disagree.

Might be worth linking the follow up tickets in a comment for posterity. /emails/reminders/cad can almost certainly go under "emails" but I know it could use a description and I think we've got that "go through misc routes" ticket still.