Add swagger / Open API support to document REST API

clarin-eric / VirtualCollectionRegistry

Virtual Collection Registry (VCR)

GNU General Public License v3.0

2 stars 0 forks source link

Add swagger / Open API support to document REST API #110

Open WillemElbers opened 3 years ago

WillemElbers commented 3 years ago

As suggested by John Shepherdson, via mail on 14 October 2020, add Add swagger / Open API support to document REST API. See https://swagger.io/docs/specification/about/

WillemElbers commented 3 years ago

Released in https://github.com/clarin-eric/VirtualCollectionRegistry/releases/tag/1.6.0-rc1

zozlak commented 3 years ago

Two questions/concerns regarding the Open API:

Where can I found the JSON file describing the VCR API which can I drop into the Swagger UI?
I'm not sure if storing a hard copy of the whole swagger UI repository inside the VCR repository is the best solution.
- It's a foreign code which will not be developed here. The more kosher way would be to link it using a git submodule
- If a working Swagger UI is needed, it's enough to store a copy of the /dist directory of the Swagger UI repo (which is a standalone HTML+JS application which doesn't require any installation on runtime environment other than a webbrowser). Anyway it's probably not worth to ship it separately for every service but it should be rather deployed as a single and separate organization-wide (CLARIN-ERIC) service.

WillemElbers commented 3 years ago

I will update the deployment to only include the /dist folder.

Currently we are not hosting the Swagger UI as a central service. However, if there are more services than can get use out of it, we can consider this.

WillemElbers commented 3 years ago

The JSON File link is provided just below the title (it is a bit hidden): https://collections.clarin.eu/swagger.json

zozlak commented 3 years ago

Thanks for the link.

I have a few more questions though:

Could you assure Access-Control-Allow-Origin: * HTTP header is emitted when it's fetched? this would allow to browse the documentation without a need to download/clone/install anything by just pasting the https://collections.clarin.eu/swagger.json URL in the https://petstore.swagger.io/ "Explore" field.
Are there chances for the submission endpoint to be included in the Open API documentation?
Are there chances for the authorization system to be included in the Open API documentation?
The JSON File link is provided just below the title (it is a bit hidden):

I looked almost everywhere - on the main github repo landing page, releases page, /doc pages - but I wasn't able to find the title and the link. Maybe it would be worth to add the link to the main repository README?

WillemElbers commented 3 years ago

CORS has been enabled on the swagger.json file and other API endpoints under /server/* for the beta instance. Interaction via https://petstore.swagger.io/ is working now. This will be deployed in production with the next release.

I will add a reference to the swagger.json file to the help page.

WillemElbers commented 3 years ago

Authorization via API keys (can be generated in the user profile page) is available via the Open API documentation.

We may add the submission endpoint to the Open API documentation at some later point in time.

zozlak commented 3 years ago

Authorization via API keys (can be generated in the user profile page) is available via the Open API documentation.

Sorry, I missed it.

We may add the submission endpoint to the Open API documentation at some later point in time.

This would be nice as the it is possible to automatically generate client code stubs in various languages from the Open API-compatible API specification (e.g. go to https://app.swaggerhub.com/apis/zozlak/arche/2.0 and click on export->client SDK in the upper-right corner) and this would allow an extremely straightforward integration with the service.