json-transcoding-openapi.md

title	author	description	monikerRange	ms.author	ms.date	uid
Use OpenAPI with gRPC JSON transcoding ASP.NET Core apps	jamesnk	Learn how to configure gRPC JSON transcoding to generate OpenAPI.	>= aspnetcore-7.0	wpickett	02/19/2025	grpc/json-transcoding-openapi

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:

// 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

• xref:grpc/json-transcoding
• OpenAPI homepage
• Swashbuckle.AspNetCore GitHub repository