ContextQMD
Back to Aspnetcore

Use OpenAPI with gRPC JSON transcoding ASP.NET Core apps

aspnetcore/grpc/json-transcoding-openapi.md

latest2.6 KB
Original Source

gRPC JSON transcoding documentation with Swagger / OpenAPI

[!INCLUDE]

By James Newton-King

OpenAPI (Swagger) is a language-agnostic specification for describing REST APIs. gRPC JSON transcoding supports generating OpenAPI from transcoded RESTful APIs. The Microsoft.AspNetCore.Grpc.Swagger package:

  • Integrates gRPC JSON transcoding with Swashbuckle.
  • Is experimental in .NET 7 to allow us to explore the best way to provide OpenAPI support.

Get started

To enable OpenAPI with gRPC JSON transcoding:

  1. Setup gRPC JSON transcoding by following the getting started instructions.
  2. Add a package reference to Microsoft.AspNetCore.Grpc.Swagger. The version must be 0.3.0-xxx or later.
  3. Configure Swashbuckle in startup. The AddGrpcSwagger method configures Swashbuckle to include gRPC endpoints.

[!code-csharp]

[!INCLUDE]

Add OpenAPI descriptions from .proto comments

Generate OpenAPI descriptions from comments in the .proto contract, as in the following example:

protobuf
// 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;
}

To enable gRPC OpenAPI comments:

  1. Enable the XML documentation file in the server project with <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Configure AddSwaggerGen to read the generated XML file. Pass the XML file path to IncludeXmlComments and IncludeGrpcXmlComments, as in the following example:

[!code-csharp]

To confirm that Swashbuckle is generating OpenAPI with descriptions for the RESTful gRPC services, start the app and navigate to the Swagger UI page:

Additional resources