Бөлісу құралы:

Документация по транскодированию gRPC JSON с помощью Swagger / OpenAPI

  • Мақала

Автор: Джеймс Ньютон-Кинг (James Newton-King)

OpenAPI (Swagger) — это не зависящая от языка спецификация для описания REST API. Транскодирование gRPC JSON поддерживает создание OpenAPI из транскодированных RESTAPI-интерфейсов ful. Пакет Microsoft.AspNetCore.Grpc.Swagger обладает следующими характеристиками:

  • Интегрирует перекодирование gRPC JSON с помощью Swashbuckle.
  • Является экспериментальным в .NET 7, чтобы позволить нам изучить лучший способ обеспечить поддержку OpenAPI.

Начало работы

Чтобы включить OpenAPI с перекодированием gRPC JSON, выполните приведенные действия.

  1. Добавьте ссылку на пакет для Microsoft.AspNetCore.Grpc.Swagger. Версия должна быть 0.3.0-xxx или более поздней.
  2. Настройте Swashbuckle в коде запуска. Метод AddGrpcSwagger позволяет настроить Swashbuckle для включения конечных точек gRPC.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGrpc().AddJsonTranscoding();
builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });
});

var app = builder.Build();
app.UseSwagger();
if (app.Environment.IsDevelopment())
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}
app.MapGrpcService<GreeterService>();

app.Run();

Примечание.

Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.

Добавление описаний OpenAPI из .proto комментариев

Создайте описания OpenAPI из комментариев в контракте .proto , как показано в следующем примере:

// My amazing greeter service.
service Greeter {
  // Sends a greeting.
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };
  }
}

message HelloRequest {
  // Name to say hello to.
  string name = 1;
}
message HelloReply {
  // Hello reply message.
  string message = 1;
}

Чтобы включить комментарии gRPC OpenAPI, выполните приведенные действия.

  1. Включите XML-файл документации в серверном проекте с помощью <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Настройте AddSwaggerGen на считывание созданного XML-файла. Передайте путь IncludeXmlComments к XML-файлу и IncludeGrpcXmlComments, как показано в следующем примере:
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });

    var filePath = Path.Combine(System.AppContext.BaseDirectory, "Server.xml");
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);
});

Чтобы убедиться, что Swashbuckle создает OpenAPI с описанием RESTслужб ful gRPC, запустите приложение и перейдите на страницу пользовательского интерфейса Swagger:

Swagger UI

Дополнительные ресурсы