Add grpc-docs support to grpc api widget #11746

kissmikijr · 2022-05-31T10:18:56Z

Hey, I just made a Pull Request!

Adds the possibility to render a generated protoc-gen-doc descriptors inside the gRPC API widget. I added this functionality into the gRPC widget because the APIs that this represents are still type: grpc, but just rendered in a nice way, something like what openapi does.

This uses the grpc-docs package to render the generated files.

With an entity setup:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  annotations:
   gendocu-com/grpc-docs: protoc-gen-doc
  name: hello-world
  description: Hello World example for gRPC
spec:
  type: grpc
  lifecycle: deprecated
  owner: team-c
  definition:
    $text: https://github.com/myOrg/myRepo/my-descriptor.json

An example gendocu json rendered in the apiwidget:

✔️ Checklist

A changeset describing the change and affected packages. (more info)
Added or updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)
All your commits have a Signed-off-by line in the message. (more info)

github-actions · 2022-05-31T10:19:21Z

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage/plugin-api-docs	plugins/api-docs	minor	`v0.8.6-next.1`

kissmikijr · 2022-05-31T13:44:52Z

I can see that the verify fails because of the usage of a private registry for one of the deps. I opened an issue in the package that I'd like to use for this work, to publish it to npm.

plaflamme

Thanks, this is great!

plaflamme · 2022-06-01T13:34:33Z

plugins/api-docs/README.md

@@ -15,6 +15,7 @@ Right now, the following API formats are supported:
 - [OpenAPI](https://swagger.io/specification/) 2 & 3
 - [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/)
 - [GraphQL](https://graphql.org/learn/schema/)
+- [gRPC](https://grpc.io/) - Using [GenDocu](https://github.com/pseudomuto/protoc-gen-doc) if configured, otherwise plain text.


GenDocu and protoc-gen-doc are separate things, developed independently. Perhaps this should mention both, e.g.:

gRPC - Using GenDocu and protoc-gen-doc plugins if configured, otherwise plain text.

plaflamme · 2022-06-01T13:36:51Z

plugins/api-docs/README.md

@@ -218,6 +219,27 @@ security:
    - [read_pets, write_pets]
 ```

+### gRPC rendering protoc-gen-doc descriptors
+
+To configure the gRPC api widget to render your generated [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) files add the following annotation to your api entities: `'backstage.io/definition-generated-by': 'protoc-gen-doc'`


In theory, there could be other plugins similar to GenDocu using the same protoc-gen-doc output. Perhaps the annotation should be gendocu-com/grpc-docs? Also, that plugin may very well decide to use a different input in the future and not rely on protoc-gen-docs at all...

Thanks, valid points, I am not familiar with this whole ecosystem, and tbh thought they are the same :D But in this case it makes much more sense to have the annotation specify the plugin that consumes theprotoc-gen-doc output

kissmikijr · 2022-06-01T17:48:37Z

@plaflamme Now that I think I start to understand how this works, and connects together a little bit more, maybe it would be better to just use only the protoc-gen-doc plugin. I think we should be able to pretty easily render the markdown output of that plugin.
With this route, we wouldn't introduce 2 new dependencies, only one, but that package seems like it is being used in the grpc world.

Wdyt?

plaflamme · 2022-06-01T19:43:56Z

@kissmikijr Although I think it can also be useful for some to show the markdown output of that plugin, I believe that the grpc-docs plugin provides a better user experience. We currently use the strategy of displaying markdown for our protocols and it's great, particularly for the more complicated ones.

I would recommend trying this on non-trivial protocols like the ones provided by Google here to get a sense of what "actual" use-cases might look like.

Rugvip

Thank you! 👍

Couple of initial thoughts

Rugvip · 2022-06-03T12:33:43Z

plugins/api-docs/api-report.md

@@ -28,7 +28,7 @@ export const ApiDefinitionCard: () => JSX.Element;
 export type ApiDefinitionWidget = {
  type: string;
  title: string;
-  component: (definition: string) => React_2.ReactElement;
+  component: (entity: ApiEntity) => React_2.ReactElement;


Wonder if we should deprecate the definition param and then grab the entity with useEntity for these instead? That way we avoid the breaking change for now and we eventually reduce the API surface.

Rugvip · 2022-06-03T12:37:41Z

plugins/api-docs/src/components/GrpcApiDefinitionWidget/GrpcApiDefinitionWidget.tsx

+    props.entity.metadata.annotations?.['gendocu-com/grpc-docs'] ===
+    'protoc-gen-doc'


This should perhaps be a different API type instead right? The definition is completely different as far as I understand

Yes, you are correct, however in this case the API entity would represent a service's API which is technically a grpc API, but got transformed to be able to render a lot more clear and in the API.
The type of an entity spec is rendered on the API catalog page in the table and if we move this to a different type it would mean that the new type will be rendered in the table.

I think you are right and trying to force it to render the correct type in the table probably not a good idea :D I'll move this to a different type!

Rugvip · 2022-06-03T12:40:29Z

plugins/api-docs/package.json

    "graphql": "^16.0.0",
+    "graphql-ws": "^5.4.1",
+    "grpc-docs": "^1.1.2",


Not hyped about the look of this dep tbh, don't really want to add it to everyones trees at this point. What do you think about perhaps making this a module instead that provides an easy way to add this rendering method to the widget API?

Makes sense, and is reasonable ask. I'll move it to a module. What do you mean by an easy way of adding this rendering method to the widget API ? Wouldn't it be a added like this: https://github.com/backstage/backstage/tree/master/plugins/api-docs#custom-api-renderings ?

Was gonna say you could provide a factory too, but realized that would create a dependency on the plugin package, so perhaps not. Would hope that we could simply export a component from the separate module that matches ApiDefinitionWidget and that the module doesn't need a dependency on the plugin.

Proper way would otherwise be a *-react package, but ain't nobody got time for that

I'll create a *-react package, shouldn't take that much longer I hope

kissmikijr requested review from a team and backstage-service as code owners May 31, 2022 10:18

github-actions bot added the awaiting-review label May 31, 2022

kissmikijr mentioned this pull request May 31, 2022

Not all dependencies are coming from well-known registry gendocu-com/grpc-docs#5

Closed

plaflamme reviewed Jun 1, 2022

View reviewed changes

kissmikijr changed the title ~~Add protoc-gen-doc support to grpc api widget~~ Add grpc-docs support to grpc api widget Jun 2, 2022

Rugvip reviewed Jun 3, 2022

View reviewed changes

backstage-goalie bot removed the awaiting-review label Jun 3, 2022

kissmikijr closed this Jun 7, 2022

kissmikijr force-pushed the add-protoc-gen-doc-support branch from a0ea00c to d76cabf Compare June 7, 2022 22:24

github-actions bot added the awaiting-review label Jun 7, 2022

kissmikijr mentioned this pull request Jun 8, 2022

Add protoc gen doc support #11923

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add grpc-docs support to grpc api widget #11746

Add grpc-docs support to grpc api widget #11746

kissmikijr commented May 31, 2022 •

edited

Loading

github-actions bot commented May 31, 2022 •

edited

Loading

kissmikijr commented May 31, 2022

plaflamme left a comment

plaflamme Jun 1, 2022

plaflamme Jun 1, 2022

kissmikijr Jun 1, 2022

kissmikijr commented Jun 1, 2022

plaflamme commented Jun 1, 2022

Rugvip left a comment

Rugvip Jun 3, 2022

Rugvip Jun 3, 2022

kissmikijr Jun 3, 2022

Rugvip Jun 3, 2022

kissmikijr Jun 3, 2022

Rugvip Jun 3, 2022

kissmikijr Jun 8, 2022

		props.entity.metadata.annotations?.['gendocu-com/grpc-docs'] ===
		'protoc-gen-doc'

Add grpc-docs support to grpc api widget #11746

Add grpc-docs support to grpc api widget #11746

Conversation

kissmikijr commented May 31, 2022 • edited Loading

Hey, I just made a Pull Request!

✔️ Checklist

github-actions bot commented May 31, 2022 • edited Loading

Changed Packages

kissmikijr commented May 31, 2022

plaflamme left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kissmikijr commented Jun 1, 2022

plaflamme commented Jun 1, 2022

Rugvip left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kissmikijr commented May 31, 2022 •

edited

Loading

github-actions bot commented May 31, 2022 •

edited

Loading