Bump to OpenAPI 3.0

[jaeddy]

With major substantive and structural changes happening to the spec en route to v1.0, I wonder if now would also be the best time to bite the bullet and convert to the latest OpenAPI spec. Not sure how much work would be involved, or whether the change would have any major impact on service/client implementors.

[mckinsel]

The changes don't seem to be too huge. The biggest benefit would probably be that we could correctly specify an arbitrary number of files to upload for workflow_descriptor.

For me, the biggest drawback is that there seems to be less tooling for openapi 3. For example, AWS API Gateway doesn't appear to work with it.

[denis-yuen]

Same here, we've been poking around at OpenAPI 3, but swagger-codegen is almost but not quite ready for compatibility. https://github.com/swagger-api/swagger-codegen#compatibility

[jaeddy]

See (and track) ga4gh/data-repository-service-schemas#230

[brainstorm]

@denis-yuen See ga4gh/data-repository-service-schemas#230 (comment), hope that helps, it worked for me with htsget and Rust:

openapi-generator generate -i spec/htsget-openapi.yaml -g rust -o src/htsget-client
openapi-generator generate -i spec/htsget-openapi.yaml -g rust-server -o src/htsget-server

(After brew install openapi-generator, that is).

[jaeddy]

Thanks, @brainstorm! I'll check that out.

@wshands— can you provide some detail for the code-gen client failures you've observed for OpenAPI 2.0 and 3.0?

[wshands]

The error I saw was that contents of the files in the workflow attachment are not included in a POST request and seems to occur in both the Swagger and OpenApi code generators. I submitted these two issues:
swagger-api/swagger-codegen#9195
OpenAPITools/openapi-generator#2210

[denis-yuen]

@brainstorm thanks for the tip, in a different issue much later we found that swagger-codegen 3.0.4 also works ga4gh/data-repository-service-schemas#230 (comment)

[patmagee]

Closing this as it looks like our API spec is currently on v 3.0