Grpc-gateway: cleanup: rename 'swagger' references to 'openapi'

[tmc]

The OpenAPI community has largely moved on from the previous name and we should follow suit.

[tmc]

@ivucica do you have thoughts here. The "grpc.gateway.protoc_gen_swagger" strings in protos will be a concern here. (I'd propose grpc.gateway.openapi, FWIW).

[ivucica]

I am comfortable with a change, aside from renaming the Swagger object, which is still the root object in OpenAPI v2.

On the other hand, how about this happens for the v3 generator (which may or may not coexist with the v2 generator)?

The problem you cite might apply only to people who want to customize their OpenAPI v2 .json by manually specifying fields that are not otherwise describable in proto format. If the rename swagger->openapi happens when they elect to use a new generator, e.g., protoc-gen-openapiv3, then it is up to them to include the new proto.

Finally, don't hold me to this, but I think package name for the options file might be a non-sequitur anyway; I don't think it applies to the wire format.

So what do you think: we don't do a rename, and instead we ask that the rename happens whenever someone contributes a v3 generator?

[philsturgeon]

Hey there, so folks closed down #872 because duplicate, so let me apply some glue and post some ccomments from that issue:

I've not yet found something that we can express in the Google http annotations that don't fit nicely into OpenAPI v2.

OpenAPI v2 didn't have the concept of nullable, which is a big pain in the backside for a lot of folks, and seeing as everything in protobuf is optional. OpenAPI v3 has that, so upgrading support would be a pretty good idea for that alone.

we'd probably still want to make sure we produce a protoc-gen-swagger

Yeah I mean sure make a placeholder package which sends people off to the right package, that's pretty standard.

As for SEO concerns, these days people are starting to understand that "Swagger" is just the name of the toolsuit from Smartbear, nothing else. Most modern projects will write "OpenAPI (formerly known as Swagger)" once somewhere in their intro, then just talk about OpenAPI from there on out.

If the concerns is SEO, I created https://openapi.tools to help push folks in the right direction too and it's getting 1000 unique visitors a day, so folks are finding it.

If you rename and add OpenAPI v3.0 support (or create a PR showing that work has begun) I'll be happy to list you up there with all the other modern OpenAPI projects! 🙌

[johanbrandhorst]

Thanks for bumping this @philsturgeon, however, I don't think any of the current maintainers are actively working on new features on the gateway, so these changes, while welcome, would have to come via interested third parties, especially the OpenAPI v3 generator. Would you be interested in contributing anything to the project?

[ivucica]

FR for OpenAPI v3 is https://github.com/grpc-ecosystem/grpc-gateway/issues/441.

I'm not aware of anyone actively working on this (beyond an occasional prospective user asking for v3 support). Contributions are welcome.

Again, I'd still suggest _not_ renaming or deleting the v2 generator. Forking it and writing a new v3 generator would be the way to go, as it would avoid issues that come with renaming a tool under active use.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[johanbrandhorst]

We should do this for v2

[johanbrandhorst]

Fixed in https://github.com/grpc-ecosystem/grpc-gateway/pull/1390