Поделиться через

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

  • Статья

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 8 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в статье о политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 8 этой статьи.

Внимание

Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

В текущем выпуске см . версию .NET 8 этой статьи.

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

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

  • Интегрирует транскодирование JSON gRPC с 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 с описанием служб RESTful gRPC, запустите приложение и перейдите на страницу пользовательского интерфейса Swagger:

Пользовательский интерфейс Swagger

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