Documenting gRPC

Documenting an gRPC service is stricly linked to the transcoding part. Usually the .proto files are considered enough documentation, but as soon as you expose them to external consumers, these will fall under the same rules as traditional APIs. gRPC JSON transcoding supports generating OpenAPI from transcoded RESTful APIs by using the Microsoft.AspNetCore.Grpc.Swagger package. To enable it on our project:

1. Install the Microsoft.AspNetCore.Grpc.Swagger package.
2. Configure Swashbuckle in startup.

Title

builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });
});

var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

Note that AddGrpcSwagger will allso add gRPC transcoding under the hood. Navigate to : https://localhost:7122/swagger/index.html , and you should see a page similar to what you've seen to other resful APIs

Generate OpenAPI descriptions

To enable gRPC OpenAPI comments:

• Enable the XML documentation file in the server project with
  true
  .
• Configure AddSwaggerGen to read the generated XML file. Pass the XML file path to IncludeXmlComments and IncludeGrpcXmlComments

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);
});