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).

[unship]

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.

[ambeur]

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.

[aeneasr]

There are several significant changes to OAS3:

1. Multi-server and server templating with the latter being particularly interesting for open source software which typically runs on different port/hosts everywhere. Can also be useful for multi-tenant services. OAS2 does not support this at all.
2. OAS3 supports all HTTP security schemes as opposed to OAS2's limited scope. Missing from OAS2 is OpenID Connect and cookie auth which is particularly interesting for browser clients (e.g. SPA) that do not support gRPC.
3. OAS3 supports polymorphism with oneOf, anyOf, and not all of which are not supported in OAS2. In OAS2 we only get allOf which limits the options we have for dealing with polymorph types in REST.
4. Better support for request bodies, and the cookie parameter type which is not implemented in OAS2.
5. OAS3 supports wildcard response codes such as 4xx where in OAS2 we need to define each error code individually, even if the output is the same (except for the status code).
6. Supports links, useful to document e.g. pagination - useful - among others - for HATEOAS compatibility.

As I've been involved in go-swagger, I know that https://github.com/go-openapi/spec3 is probably not going to see involvement from the original author. He stated in an issue that he does not intend to work on this any more as it is too much work.

I know that this is a lot of work to implement, but given previous comments around what actually changed I thought it's a good idea to provide a short list of interesting changes. I think supporting OAS3 spec generation could help a lot of OSS projects in their API documentation and REST client generation!

[achew22]

@aeneasr I don't think anyone is saying that the request is invalid or a bad idea. In reading the scrollback it sounds like the problem is that the marginal effort to adopt OpenAPI v3 is not worth the marginal effort for existing maintainers.

It sounds like the calculus might be different for you. How can I/we help you in the process of bringing OpenAPI v3 support into grpc-gateway?