Update our own docs to OAS 3.0

Update our own docs to OAS 3.0

Dev notes

Spec definition

3scale docs are currently auto-generated by a very outdated tool called source2swagger that turns comments into a swagger 1.x spec. The comments have a particular format and are also useful to document the code.

There are many libraries that convert OAS 2 into 3 but only a few that are compatible with OAS 1. One example is https://github.com/LucyBot-Inc/api-spec-converter. It should be possible to add this tool to the current pipeline (rake doc:swagger:generate) but it’s prone to errors, probably because of our definition is not 100% correct and source2swagger doesn’t validate it. It’s also worth mentioning that because we’re using our own implementation of swagger-ui, these definition errors have passed under the radar.

Using source2swagger is no longer a viable option if we’re to support OAS3. There are other libraries that auto-generate specs from text or code but it is probably easier and quicker to convert our existing specs to OAS3, fixing any errors manually (almost all of them are related to the same type of parameters) and have a proper OAS 3 spec definition that will be maintained manually.

UI

Porta already supports swagger-ui-3 and it’s being used in the Active Docs section.

Scope of this issue

Under rolling update, display our MT API doc as OAS 3.0 spec without any extra features (autocompletion of keys, application_id etc...)

Note: There is already an experimental support for OAS 2 behind the rolling-update new_provider_documentation. However, all the work involved, expect for the rolling-update, has to be updated.