search

envoyproxy / envoy

Cloud-native high-performance edge/middle/service proxy
https://www.envoyproxy.io
Apache License 2.0
24.94k stars 4.8k forks source link

Swagger/OpenAPI generated documentation from gRPC-JSON transcoder #6334

Closed mattbailey closed 5 years ago

mattbailey commented 5 years ago

Title: Generating swagger or openapi json from gRPC-JSON transcoder

Description:

The REST API that is derived from gRPC-JSON is somewhat unknown. Can envoy generate swagger or openapi documentation from transcoding in the same way that grpc-gateway protoc tooling does? Then either serve it up from /openapi.json and/or request the spec from envoy's v2 API somehow?

501 suggests this might have been an idea, I can't find any other references to it.

Relevant Links:

Mentioned by @mattklein123 at the end of this issue thread: #501 Sort of relevant: #2770

mattklein123 commented 5 years ago

cc @lizan seems like an interesting potential enhancement.

mattbailey commented 5 years ago

Is there a current-best-practice way to inspect the request/response shape of the generated API transcoding filter?

lizan commented 5 years ago

Yeah it is an interesting enhancement. @mattbailey can we just re-use the protoc-gen-swagger from grpc-gateway, and serve the generated openapi.json, if so probably just add docs for that is enough.

mattbailey commented 5 years ago

Yeah it is an interesting enhancement. @mattbailey can we just re-use the protoc-gen-swagger from grpc-gateway, and serve the generated openapi.json, if so probably just add docs for that is enough.

@lizan that was my initial approach, but I have no way of knowing that protoc-gen-swagger, which is intended to document protoc-gen-gateway's transcoding, produces the same API. Although it was modeled after it, gRPC-JSON doesn't use protoc-gen-gateway under the hood right?

Might be enough for a stop-gap, but I'd be worried changes in envoy or protoc-gen-gateway/swagger either do now, or may in the future, create subtle changes in the transcoder or the swagger.

stale[bot] commented 5 years ago

This issue has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in the next 7 days unless it is tagged "help wanted" or other activity occurs. Thank you for your contributions.

stale[bot] commented 5 years ago

This issue has been automatically closed because it has not had activity in the last 37 days. If this issue is still valid, please ping a maintainer and ask them to label it as "help wanted". Thank you for your contributions.

codyaray commented 5 years ago

Any more thought on this? Would be interested in it

mattbailey commented 5 years ago

I think this is even more relevant now with the addition of the auto_mapping feature: https://www.envoyproxy.io/docs/envoy/latest/api-v2/config/filter/http/transcoder/v2/transcoder.proto.html?highlight=auto_mapping

Since protoc-gen-swagger apparently just leaves endpoints out entirely if they don't have annotations.

dzolotusky commented 5 years ago

@lizan @mattbailey is there any update on this? I'd be happy with some documentation on how to generate this manually for now. Though, I don't think that that exists at the moment.

mattbailey commented 5 years ago

@lizan @mattbailey is there any update on this? I'd be happy with some documentation on how to generate this manually for now. Though, I don't think that that exists at the moment.

I am still using the protoc-gen-swagger from https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-swagger which has been mostly effective, but their are blind spots, e.g.: https://github.com/envoyproxy/envoy/issues/3383

lizan commented 5 years ago

@mattbailey Fix for #3383 is merged yesterday.

mattbailey commented 5 years ago

@mattbailey Fix for #3383 is merged yesterday.

Yeah, and it's awesome, been watching it, I just haven't checked whether it maps to what is generated by protoc-gen-swagger yet.

dzolotusky commented 5 years ago

OK, thanks. It'd be great to have something simpler than using protoc-gen-swagger, but that's a good start for now.

isururanawaka commented 3 years ago

Any update on this? we are using envoy proxy to convert gRPC to REST and we need to have swagger based interactive API documentation

mattbailey commented 3 years ago

I'm still personally using protoc-gen-swagger, and we've centralized our proto files which seems to have a number of benefits. It still would be extremely handy, of course.

gektor0856 commented 2 years ago

it still relevant in 2022, any updates?

gektor0856 commented 2 years ago

it still relevant in 2022, any updates?

May be usefull - resolved by gnostic tool.Using protoc-gen-openapi it can produce openapi spec from proto file