Skip to main content

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