Discrepancies between Swapper and OpenAPI definitions for Dockstore API

Dockstore
1

I might have found discrepancies between the Swagger 2.0 and OpenAPI 3.0 definitions for the Dockstore API. This is my first time using these kinds of files, so bear in mind that I might be doing something wrong without realizing it. For context, I’m using these files to import the API definition into Postman.

Specifically, I’m interested in testing the TRS 2.0.0 API endpoints, which appear under the GA4GHV20 tag on the Swagger API documentation page (can’t include this as a third link because of new user limit). However, when I tried importing the Swagger JSON definition, it lacked the relevant TRS 2.0.0 endpoints. Nothing comes up if you search the JSON for /ga4gh/trs/v2/. On the other hand, if you download the OpenAPI YAML definition, you can indeed find the /ga4gh/trs/v2/ endpoints.

Is there a reason why the /swagger.json endpoint would be returning an outdated (?) API definition?

2

Hey Bruno, Dockstore has been slowly migrating to only use OpenAPI 3.0. Since the decision to migrate, our newer endpoints are only getting defined with OpenAPI, and not both. On top of that, endpoints that were created before the decision, may not be completely updated on the OpenAPI side as well. So, there will be discrepancies between the two.

3

That would explain it. May I suggest that the /swagger* endpoints be marked as deprecated (and perhaps point to the link for the OpenAPI YAML file since it’s easy to miss in the documentation)?