#grpc #documentation #openapi
Вопрос:
В идеале я хотел бы иметь возможность передавать только мои файлы protobuf. Эти файлы содержат определения rpc (со всеми необходимыми телами запросов / ответов) и опцию google.api.http, которая позволяет создать http-прокси, чтобы клиенты могли вызывать либо gRPC, либо json / http. Вторым лучшим был бы инструмент, который использует файлы proto и swagger для создания документов единообразным образом.
Существует множество инструментов для создания только документации OpenAPI, некоторые из которых я нашел https://mrin9.github.io/RapiDoc/https://lucybot.com/docgen и https://redoc.ly/pricing . Они генерируют красивые документы на основе файлов swagger. Но ни один из них не поддерживает gRPC.
Единственный инструмент, который я нашел для создания документации gRPC, размещенной самостоятельно, — это https://github.com/pseudomuto/protoc-gen-doc . Инструмент в порядке, но пользовательский интерфейс просто не соответствует современным стандартам IMO.
В настоящее время я использую классический smartbear swagger для моего http и protocol-gen-doc для моего grpc, чтобы создать две совершенно отдельные страницы для моей документации. Но пользовательский интерфейс не совпадает, и они находятся на разных URL-путях. В идеальном мире между ними было бы переключение на одной странице.
Я провел немало исследований по этой теме, поэтому я не уверен, что другие смогут найти. По крайней мере, возможно, этот пост покажет другим, что на рынке существует пробел. Я думаю, что инструменты документации gRPC могут принести кому-то много денег.
Комментарии:
1. Привет, Пол, я соучредитель Bump ( bump.sh ). Мы пока не поддерживаем gRPC, но планируем это сделать. В настоящее время мы поддерживаем OpenAPI 2/3 и AsyncAPI. Я согласен с тем, что сегодня существует реальная нехватка инструментов для документирования gRPC. Дайте нам знать, если вы найдете лучший вариант, чем protocol-gen-doc. (Если вы хотите поговорить об этом, я буду рад провести с вами небольшую беседу, чтобы лучше понять ваш вариант использования.)
Ответ №1:
Наиболее близким решением является gRPC Docs от Gendocu Cloud. Это компонент React, который отображает документацию json, сгенерированную protoc-gen-doc . К сожалению, он может отображать только документацию gRPC.