Endpoints Portal | Mixing up documentation when using different packages

[Jan Krynauw]

Problem encountered:

When deploying protos with different packages, messages with the same name are mixed up between the packages.  For example, a 'RunRequest' messages defined in packages 'service' and 'test' are not differentiated.  The Developer Portal does not differentiate between packages.

 

Expected to happen:

That the Developer Portal resources are uniquely defined as in their respective packages/namespaces.  i.e. say a method 'Run' in Service1 is different to the method 'Run' in Service2.

Steps to reproduce:

I've created a simplified example (see attached .zip file with all the details, including a simple shell script to deploy).  Here are screenshots of the two .protos in two packages: 'service' and 'test' and the corresponding Cloud Endpoint portal representation.

Current workarounds:

The current workaround would be to deploy each package as its own Service  - not practical as we have 100s of services

Another workaround would be to ensure unique message names across all services - again not practical with 100s of services.

[Teju Nareddy]

Thanks for the report and detailed reproduction steps. I remember seeing a similar problem recently, but I do not have much context on it.

+Josh Einhorn +Alan Peters +Jeremy Whitlock can you take a look?

FWIW this is only a problem with the Endpoints Portal. The actual ESP / ESPv2 instance will handle traffic correctly, it's just the portal UI that mixes up the package names.

--
You received this message because you are subscribed to the Google Groups "Google Cloud Endpoints" group.
To unsubscribe from this group and stop receiving emails from it, send an email to google-cloud-endp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/google-cloud-endpoints/8c9a12ce-2f28-43f7-a04e-ce3fa7bc5d84n%40googlegroups.com.

--

Teju Nareddy nare...@google.com Software Engineer

[Josh Einhorn]

Hi again Jan,

I'd recommend filing a formal feature request if you haven't already yet; this helps our Product Managers prioritize the work. Because this has not been formally prioritized, we're not currently in a position to address the issue at the source (the Endpoints Portal). It would help Product if you could briefly describe the use case for your dev portal and the impact of not having this feature.

Sorry we can't be of more help at this very moment; this is indeed an actual limitation of the Portal implementation that you discovered (thanks for pointing it out to us though).

-Josh

--

Josh Einhorn |

Software Engineer |

joshe...@google.com |

1-215-837-1102

[Jan Krynauw]

Thanks - I logged it here: https://issuetracker.google.com/issues/172775986

@teju, that is correct, we have many of these services deployed segregated by packages as gRPC endpoints written in Go and the ESPv2 behaves as expected.  We are just unable to use the Endpoints Portal.  I believe it has to be a bug with smart docs?

In the meantime, is there a tool we could consider to help with documentation while the above is investigated?

Having .proto files driving everything is super elegant.

[Josh Einhorn]

Unfortunately Google does not offer a tool to convert gRPC to more human-friendly documentation besides SmartDocs.

Unofficially, you may check out some open source tools to generate documentation, such as protoc-gen-doc. This of course is entirely unaffiliated with Google, not supported by Google, and requires you to manage the web server if you wish to expose this as a website, however it may solve your problem.

-Josh

[Jan Krynauw]

Thanks!