gRPC-swagger

gRPC-swagger — это инструмент для отладки gRPC, разработанный на основе gRPC reflection. Он позволяет удобно просматривать и вызывать методы gRPC с помощью swagger-ui. Поскольку gRPC-Swagger основан на отражении gRPC, при запуске службы необходимо включить функцию отражения, при этом не требуется изменять файлы proto и связанный код реализации.

Что такое gRPC-swagger?

gRPC-swagger — это инструмент отладки gRPC, созданный на основе gRPC Reflection. Его можно использовать для удобного просмотра и вызова методов gRPC с использованием swagger-UI. Поскольку gRPC-swagger основан на gRPC Reflection, вам нужно только включить функцию Reflection при запуске сервиса, без необходимости изменять протофайлы и связанные реализации кода.

Список функций

• Простота в использовании: просто включите функцию отражения при запуске сервиса без изменения протофайлов и связанных реализаций.
• Интеграция с swagger-UI: вы можете легко просматривать определения методов и параметров gRPC.
• Простота вызова метода gRPC.

Скриншоты

На скриншотах показаны примеры интерфейса программы.

Живая демонстрация

demo

Сборка и запуск

Использование выпущенного jar

wget https://github.com/grpc-swagger/grpc-swagger/releases/download/0.1.1/grpc-swagger-web-0.0.1-SNAPSHOT.jar
java -jar grpc-swagger-web-0.0.1-SNAPSHOT.jar

Сборка из исходного кода

mvn clean package
java -jar grpc-swagger-web/target/grpc-swagger-web-0.0.1-SNAPSHOT.jar

По умолчанию он запускается через порт 8080, используйте --server.port=yourport, если вы хотите использовать другой порт.

java -jar grpc-swagger-web/target/grpc-swagger-web-0.0.1-SNAPSHOT.jar --server.port=8888

Как использовать

1. Запустите gRPC-swagger, следуя инструкциям Сборка и запуск.
2. Включите отражение при запуске сервиса. Ниже приведён пример на Java: добавьте зависимость в pom.xml:

   <dependency>
       <groupId>io.grpc</groupId>
       <artifactId>grpc-services</artifactId>
       <version>${grpc.version}</version>
   </dependency>
   включите отражение:

   Server server = ServerBuilder.forPort(SERVER_PORT)
       .addService(new HelloServiceImpl())
       .addService(ProtoReflectionService.newInstance())
       .build()
       .start();
3. Зарегистрируйте конечную точку. Вы можете зарегистрировать конечную точку, на которой работают сервисы gRPC, в gRPC-swagger через интерфейс register, gRPC-swagger автоматически просканирует доступные сервисы и вернёт успешно зарегистрированные сервисы после завершения. Зарегистрированные сервисы можно просмотреть через интерфейс listServices. Для удобства использования мы предоставили простую HTML-страницу здесь.
4. Используйте swagger-UI для просмотра сервисов gRPC. Введите <host:port>/v2/api?service=<fullServiceName> в поле ввода вверху, где fullServiceName — это имя успешно зарегистрированного сервиса выше.
5. Нажмите кнопку «Попробовать», чтобы протестировать метод gRPC. ### Список сервисов

URL: /listServices

Пример ответа:

{
    "code": 0,
    "data": {
        "localhost:12347": {
            "groupName": "localhost:12347",
            "services": [
                "io.grpc.grpcswagger.showcase.HelloService"
            ],
            "endpoints": [
                "localhost:12347"
            ],
            "success": true
        }
    }
}

Вызов метода gRPC

URL: /{rawFullMethodName}

Параметры:

• rawFullMethodName — полное имя метода gRPC, например, io.grpc.grpcswagger.showcase.HelloService.GetUser.
• payload — параметры метода gRPC в формате JSON. Для указания вызываемой конечной точки можно использовать параметр endpoint.

Swagger API

URL： /v2/api-docs

Возвращаемые данные используются swagger-ui.

Параметры:

• service — полное название сервиса, например, io.grpc.grpcswagger.showcase.HelloService.

Благодарность

Благодаря проекту polyglot логика отражения в нашем проекте была изменена на polygolt.

Вклад

Не стесняйтесь открывать вопросы или запросы на вытягивание. Мы будем признательны!

Часто задаваемые вопросы

Лицензия

Лицензия MIT.