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 #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!

[glpatcern]

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!

Well, again we have quite a number of ongoing PRs, and this branch is already in conflict with the current HEAD. I'd postpone this until we settle them (and before tagging 1.2).

[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!

[mickenordin]

It is very hard to follow all the changes in detail, but looking at the spec viewer I don't see any apparent errors at least.

[glpatcern]

I've just removed the empty lines, otherwise as Micke said it's hard to follow the changes but as long as the rendering looks correct let's go!