Bump OAPI 2 to OAPI3 (Autogenerated)

[susheel]

Will need to check and verify before merging as the changes are extensive.

This is a dependency to set up the service-info PR #144

[dglazer]

@susheel , the last time I remember us talking about upgrading to OAPI3, we didn't know how to get the auto-generated documentation to work, so we decided to stick with OAPI2. Has that been resolved? (I'm guessing not, since the Travis CI checks failed, but maybe those are unrelated errors?). Adding @jaeddy in case he remembers more about the details.

[briandoconnor]

Yep, I see this error in the travis CI build log:

The command "pip install . --process-dependency-links" failed and exited with 2 during .

@susheel I'm assuming you bumped the version to 3 so you could use this construct to extend service-info:

"Your OAS 3 API might want to define additional service information as well. To do that, use the allOf OAS 3 construct."

Is that right?

[susheel]

@briandoconnor Yes, we needed to bump it to OAPI3 to support the allOf construct. I haven't been able to check the travis build, but the autogenerated YAML works in the online swagger checker for the OA3-upgrade yaml.

We may need to bump the travis build packages to OAPI3 too.

[dglazer]

@susheel , I understand that OAPI 3 supports some new features. However, at least last time we looked at it, it also broke the auto-generated documentation, so we decided not to take advantage of those new features. Not a great choice to have to make, but until it's resolved, we either have to find a whole new way of keeping our documentation up to date, or stick with OAPI 2. @jaeddy may remember more details.

However we resolve, we need to make sure we'll have clean updated documentation before merging this in.

[jaeddy]

Hey @susheel, @dglazer — I've been working on a little tool for the past few months that would replace swagger2markup (no support for OpenAPI 3.0) with ReDoc and/or Sphinx+ReadTheDocs. This would also address some of our build issues (and vulnerability warnings) by moving that logic to an independent package.

It's been a while since I've been able to make progress on the tool, but I'll discuss with another engineer on my team and see if he can pick up the remaining development to get something working. Once we get those changes made, it'd be great to review and merge this PR.