Swagger/OpenAPI를 사용한 gRPC JSON 코드 변환 설명서

작성자: James Newton-King

OpenAPI(Swagger)는 REST API를 설명하는 언어 중립적 사양입니다. gRPC JSON 코드 변환은 코드 변환된 RESTful API에서 OpenAPI 생성을 지원합니다. Microsoft.AspNetCore.Grpc.Swagger 패키지:

• gRPC JSON 코드 변환을 Swashbuckle과 통합합니다.
• .NET 7에서 OpenAPI 지원을 제공하는 가장 좋은 방법을 탐색할 수 있도록 실험적으로 수행됩니다.

시작하기

gRPC JSON 코드 변환을 사용하여 OpenAPI를 사용하도록 설정하려면 다음을 수행합니다.

1. Microsoft.AspNetCore.Grpc.Swagger에 대한 패키지 참조를 추가합니다. 버전은 0.3.0-xxx 이상이어야 합니다.
2. Startup에서 Swashbuckle을 구성합니다. AddGrpcSwagger 메서드는 gRPC 엔드포인트를 포함하도록 Swashbuckle을 구성합니다.

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.org에서 올바른 패키지 버전을 확인합니다.

.proto 주석에서 OpenAPI 설명 추가

다음 예제와 같이 .proto 계약의 주석에서 OpenAPI 설명을 생성합니다.

// 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. <GenerateDocumentationFile>true</GenerateDocumentationFile>을 사용하여 서버 프로젝트에서 XML 설명서 파일을 사용하도록 설정합니다.
2. 생성된 XML 파일을 읽도록 AddSwaggerGen을 구성합니다. 다음 예제와 같이 IncludeXmlComments 및 IncludeGrpcXmlComments에 XML 파일 경로를 전달합니다.

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이 RESTful gRPC 서비스의 설명을 사용하여 OpenAPI를 생성하고 있는지 확인하려면 앱을 시작하고 Swagger UI 페이지로 이동합니다.

추가 리소스

• ASP.NET Core gRPC 앱에서 gRPC JSON 코드 변환
• OpenAPI 홈페이지
• Swashbuckle.AspNetCore GitHub 리포지토리