Open API 2.0 (swagger) yaml implementation

[ivandov]

Using the Open API Specification to describe the Open Service Broker API is very much needed, but unfortunately not many existing tools work with the OAS3 specification yet. However, many tools and generators work with the Open API 2.0 (or Swagger) spec.

I've manually ported the openapi.yml file to be backwards compatible with the 2.0 specification. I've kept as many of the fields and descriptions the same as in the 3.0 specification with the exception of deprecated which was not supported on the properties objects. Also, the servers 3.0 root element does not have a 'natural' port to the 2.0 specification, so I omitted it, but it can be potentially replaced with the host root element.

I've done a manual side-by-side comparison of the OAS3 and 2.0 definition in editor.swagger.io and do not see any differences.

[cfdreddbot]

Hey ivandov!

Thanks for submitting this pull request!

All pull request submitters and commit authors must have a Contributor License Agreement (CLA) on-file with us. Please sign the appropriate CLA (individual or corporate).

When sending signed CLA please provide your github username in case of individual CLA or the list of github usernames that can make pull requests on behalf of your organization.

If you are confident that you're covered under a Corporate CLA, please make sure you've publicized your membership in the appropriate Github Org, per these instructions.

Once you've publicized your membership, one of the owners of this repository can close and reopen this pull request, and dreddbot will take another look.

[duglin]

@ivandov can you sign the CLA?

[rhodie27]

Validates nicely. I generated a server using this. Looks good. TY.

[ivandov]

@duglin Sure, I believe IBM has a CLA with Cloud Foundry. Is there any way to verify this?

[duglin]

@ivandov can you sign the CLA?

[ivandov]

@duglin As I mentioned before, I believe I may be covered by the IBM CLA. Can this be verified?

[cfdreddbot]

Hey ivandov!

Thanks for submitting this pull request! I'm here to inform the recipients of the pull request that you and the commit authors have already signed the CLA.

[duglin]

@ivandov ah sorry- I forgot you said that - yes we're all good now.

[n3wscott]

LGTM

[duglin]

@ivandov you have an outstanding comment/suggested edit - did you want to address it?

[n3wscott]

@ivandov you have an outstanding comment/suggested edit - did you want to address it?

We can always fix it on a follow-up. It is just a nit and very nitty :D

[ivandov]

@duglin @n3wscott - After receiving the comment, I had removed the extra whitespace in commit https://github.com/openservicebrokerapi/servicebroker/pull/444/commits/41f6731b1542659389fcc61fb69819f4ca847480

The latest version that is pending approval no longer has this whitespace.

[ivandov]

Oh wait, now I see there was another comment for whitespace between the top comment block and the beginning of the swagger definition. I can push another update to remove that or as @n3wscott mentioned, it's very much a nit, and can be easily updated after the initial accepted merge.

Up to you guys on how you want to handle it. @n3wscott Seems to approve the PR pretty quickly, and no other other response from any other approvers as of yet, so... If I update it, and @n3wscott approves quickly, we'll be in the same state as we are now.

[duglin]

just make @n3wscott re-approve :-) we might as well just fix it now

[ivandov]

@duglin @n3wscott nit fixed - following openapi.yaml styling ... please review.

[n3wscott]

LGTM

I have been tasked with finding a way to keep this and the v3 version in sync... Still looking

[ivandov]

@n3wscott before I created this swagger yaml, I searched for a tool that would convert the 3.0 spec back to 2.0, with no luck. I do believe there are tools for converting 2.0 to 3.0, in which case all you'd need to do there is add the additional servers block that 3.0 added. But, I'm sure I'm oversimplifying it.

[duglin]

LGTM

[duglin]

LGTM again

[duglin]

@n3wscott I think you need to do yours again too

[n3wscott]

LGTM

[vaikas]

LGTM

[duglin]

Need just one more!! Who wants the thrill??

[fmui]

LGTM