다음을 통해 공유

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

  • 아티클

참고 항목

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

Warning

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

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .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. 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 페이지로 이동합니다.

Swagger UI

추가 리소스