Openapi 3

[butonic]

I was confused by the examples for /share and converted the spec from swagger to openapi which allows using multiple examples. IMO we should update to openapi to better document how the api should be used.

This PR consists of four commits:

1. convert to openapi v3 (it explicitly uses application/hal+json for a lot of responses, but I don't know how critical that is)
2. use multiple share examples
3. use multiple notification examples
4. deprecate protocol options property

Let me know what you think.

[butonic]

urgh, now I see https://github.com/cs3org/OCM-API/pull/64

[glpatcern]

urgh, now I see #64

I think we can close that one that is now outdated, and concentrate on this one.

[glpatcern]

@butonic could you please rebase this? I think it's very valuable at this stage - and with no outstanding change/tuning of the specs - to move to OpenAPI. And we could then envisage to tag OCM v1.2.0.

[mickenordin]

Current version of spec can easily be converted to openapi 3 using the following command:

npx -p swagger2openapi swagger2openapi https://raw.githubusercontent.com/cs3org/OCM-API/develop/spec.yaml --outfile spec.yaml -t 3.0.3

[michielbdejong]

I ran that and pushed it to the openapi3 branch. Does https://cs3org.github.io/OCM-API/docs.html?branch=openapi3&repo=OCM-API&user=cs3org#/paths/~1invite-accepted/post look OK? If so we can switch to it!

[michielbdejong]

I ran the script on latest develop and force-pushed. How can we test if it is OK?

[michielbdejong]

Ah, https://cs3org.github.io/OCM-API/docs.html?branch=openapi-3&repo=OCM-API&user=cs3org looks OK I think?

[mickenordin]

Ah, https://cs3org.github.io/OCM-API/docs.html?branch=openapi-3&repo=OCM-API&user=cs3org looks OK I think?

Yes! Looks good to me!