다음을 통해 공유

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

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 10 버전을 참조하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

작성자: James Newton-King

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

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

시작하기

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

  1. 시작 지침에 따라 gRPC JSON 코드 변환을 설치합니다.
  2. Microsoft.AspNetCore.Grpc.Swagger에 대한 패키지 참조를 추가합니다. 버전은 0.3.0-xxx 이상이어야 합니다.
  3. 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 페이지로 이동합니다.

Swagger UI

추가 리소스

  • Last updated on