Grpc-gateway: Feature Request: OpenAPI 3 support

[c4milo]

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

[achew22]

@c4milo, Can you elaborate on what it is you're interested in that isn't available today?

[c4milo]

@achew22, feature wise, nothing. What's concerning to me right now is that https://github.com/swagger-api/swagger-js/tree/2.x is no longer active. Most development effort is going towards supporting OpenAPI v3.

[zxy198717]

+1

[johanbrandhorst]

The OpenAPI 3.0 spec has added support for Authentication (JWT, Oath, HTTP Basic), which is something that is missing from 2.0. I think this would make it worthwhile to migrate to generating 3.0 compliant definitions.

[jsw]

Also oneof?

[tamalsaha]

I suppose https://github.com/go-openapi/spec3 will be needed first.

[ivucica]

@johanbrandhorst Strictly speaking, that's not something that makes v3 support a must and a requirement. Consider that OpenAPI v2 does support OAuth2 authentication, Basic authentication and API keys.

I don't see in that PR where OpenAPI v3 adds JWT, and I suppose you meant OAuth2 and not OATH (different thigns)?

What I see as a new thing in that PR you quoted is "HTTP Bearer" and "Multiple Flows", which both may be useful. (Even though Bearer will be usually used with OAuth2, anyway, there might be people out there not using it that way.)

@tamalsaha That would be the right way to go, but protoc-gen-swagger has OpenAPI v2 schema, so that's not a blocker either.

[veqryn]

OpenAPI v3.0.0 adds support for specifying multiple servers (hosts).

[llvim]

oneof sematics is a pain point for us

[jones77]

OpenAPI 3.0 adds support for nullable types, 2.0 doesn't support them: https://github.com/swagger-api/swagger-editor/issues/1364#issuecomment-309530250

[johanbrandhorst]

I'm pretty sure there's an extension for V2 (x-nullable?).

[johanbrandhorst]

https://github.com/grpc-ecosystem/grpc-gateway/issues/900 is a real issue that would be covered by this.

[ivucica]

FTR I will be very happy to review forks of the swagger generator, or elegant refactors of the swagger generator that allow for both openapiv2 and openapiv3.

[misrab]

+1

[lukaskellerstein]

+1

[zachgersh]

Hey everyone,

So we are actually doing this (at least I am going to try). I pushed the first bits of OPENAPI v3 support and attached the WIP PR to this issue for all to review.

I'd love everyone to go have a look at the proto and WIP if they can. I WANT YOUR FEEDBACK ON THIS. Would love to know what sort of fields are required missing from the next version of this generator.

[ivucica]

@zachgersh I still have the notification email for your comment marked as 'unread' in my inbox, this is exciting and I hope to take a look soon.

[JugrajSripalJain]

is this done, if not, do we have any ETA?

[ivucica]

I am not doing this myself and I have not seen activity on #1059. @JugrajSripalJain, you can review my comments there and see if they align with the way you'd like to implement this.

[zachgersh]

It's not done and no ETA as of yet. I put this down for a bit as other work jumped my queue. We do plan to come back to this some point in Q1 next year but I'd be happy to see someone else grab it if they have time now.

[zvnt]

hi, is there any news about this feature?

[glebmachine]

Looking forwards OAS3 support, could you share your current plans about?

[johanbrandhorst]

I think this is on ice again unfortunately. If someone would like to pick this up please let me know.

[srenatus]

ℹ️ Should we want to do this, here's an auto-generated protobuf model of OpenAPI v3 (and v2, for that matter): https://github.com/googleapis/gnostic/blob/master/openapiv3/OpenAPIv3.proto

[krishna-birla]

Coming here from https://github.com/googleapis/gnostic/issues/162

@srenatus https://github.com/googleapis/gnostic doesn't inter-convert between proto files and open API specs, it uses message buffers instead (binary serialized data). More over, the open API specs to proto files conversion does not exploit the newest oneOf feature as expected. I have posted some use cases in the issues there. And lastly, the better use case is to manually write proto files and then generate both gRPC and REST clients/servers from it.

It would be great to have it in grpc-gateway itself. Happy to contribute.

[johanbrandhorst]

We'd love to have openapi 3 support! Please know that it may be a lot of work. Please have a look at the v2 branch and you can probably use protoc-gen-openapiv2 as a starting point.

[zwiedmann-isp]

@johanbrandhorst @krishna-birla I'm willing to contribute where I can as well, tho my time is limited, and at present time I'm able to get away with v2 generation and conversion using https://github.com/getkin/kin-openapi/tree/master/openapi2conv . @johanbrandhorst if you able to provide any context on the gist of the work as you understand it that'd be helpful. At present time it's not entirely clear to me why we define openapiv2.proto files and what we would define a v3 variant to achieve. Of course I'm sure once I dig into the code that'll be clearer.

[johanbrandhorst]

Thanks! Frankly, I'm not sure what the need is either, I've been getting by with v2 wherever I've needed it. I'll be happy to help answer questions about the code but I'm no expert on openapi.