search

HDFGroup / hdf-rest-api

12 stars 5 forks source link

OpenAPI Specification errors #4

Closed bilalshaikh42 closed 3 years ago

bilalshaikh42 commented 3 years ago

Thank you for your work on this API! It is a very useful bridge between the HDF5 format and web applications.

The OpenAPI definitions for the API provided in the 'openapi' branch currently have the following two errors as reported by the SwaggerHub editor: 

Line    Error
198     Path parameter "FolderSpec" must have the corresponding {FolderSpec} segment in the "/" path
2395    Path parameter "ACLDefinition" must have the corresponding {ACLDefinition} segment in the "/acls/{user}" path

Would you be open to pull requests to fix these errors? I can see based on the older swagger definition that these parameters are provided in the body, instead of the path as stated in the OpenAPI definition. I am unsure if the issue regarding the "FolderSpec" parameter provided as both a query param and body has been resolved.

Context

I am working on the BioSimulations project, an NIH funded academic project to enable researchers to reproduce and reuse biological simulations. We would like to use the HSDS as a backend for storing our simulation results, as it provides a great interface for querying and accessing the data stored on the cloud.

I was hoping to use the OpenAPI definitions for the hdf-rest-api to generate typescript client code that can be integrated into our existing web services. The current issues do not allow for code generation to work.

jreadey commented 3 years ago

Hey @bilalshaikh42, sorry for not updating this issuer earlier. This project has been moribund for a while, but I agree it would be very useful to have an OpenAPI specification. Please take a look at the openapi branch that @ajelenak created recently and let us know how that works for you. We're planning to actively work on the specification, but it may take a while to get caught up with recent updates to the HSDS service.

bilalshaikh42 commented 3 years ago

That branch was quite helpful in getting started. I have made a couple of fixes for some of the syntax issues and was able to get started on some of the todos that were mentioned. I accidentally included some of our own internal use case changes in the original pull request, so I closed it, but I can definitely create another pull request to help with the spec. Would you be open to creating an openAPI spec in the master branch? I can then open pull requests against it and request approval for the changes

jreadey commented 3 years ago

I've fixed the two errors. Changes are checked into the openapi branch and I've merged that branch to master. If you have additional fixes, please open a PR and I'll be happy to review.