Add support for gRPC Swagger

[profnimrod]

Is your feature request related to a problem? Please describe.

I wonder if support for a project like gRPC Swagger (https://github.com/grpc-swagger/grpc-swagger) could be added. Or perhaps better, support for gRPC Gateway (https://github.com/grpc-ecosystem/grpc-gateway) where if the appropriate REST options are included in the proto, a REST API controller is automatically created, which can then be readily documented using Swagger/OpenAPI.

Describe the solution you'd like

If the appropriate REST option is added to the proto service definition, e.g.,

service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply){
option (google.api.http) = {
post: "/api/controller/sayhello"
body: "*"
};
}

then a Web API controller is automatically created with the appropriate name and methods. The startup file is updated to include the controller and endpoints. To this Swagger could be manually added.

[JunTaoLuo]

Have you taken a look at https://github.com/aspnet/AspLabs/tree/master/src/GrpcHttpApi?

[profnimrod]

Ah, I hadn't. Looks interesting. I've cloned the repository but having trouble compile the relevant projects :-(

[JunTaoLuo]

Can you add more details on what issues you're running into?

[profnimrod]

Sure thing - after making sure I had the last .Net Core 3.0 SDK and runtime installed I still get:

Severity Code Description Project File Line Suppression State

Error Unable to find package Microsoft.DotNet.Arcade.Sdk. No packages exist with this id in source(s): gRPC, NuGet.org (v3) Microsoft.AspNetCore.Grpc.HttpApi 5

Severity Code Description Project File Line Suppression State

Error C:\Program Files\dotnet\sdk\3.0.102\Sdks\Microsoft.DotNet.Arcade.Sdk\Sdk not found. Check that a recent enough .NET Core SDK is installed and/or increase the version specified in global.json. Microsoft.AspNetCore.Grpc.HttpApi 5

[JunTaoLuo]

The Microsoft.AspNetCore.Grpc.HttpApi package is not published anywhere. You need to build and pack the project https://github.com/aspnet/AspLabs/tree/master/src/GrpcHttpApi/src/Microsoft.AspNetCore.Grpc.HttpApi and consume the package.

[profnimrod]

Thanks - yes I get that and that is what I was trying to do, but it failed to build because it couldn't find Microsoft.DotNet.Arcade.Sdk which I'd never heard of. Fixed it by adding "https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-eng/nuget/v3/index.json" to my NuGet package source. Have successfully built now and can hopefully do some testing.

[profnimrod]

OK - got it working... sweet! This is certainly moving in the right direction for what I'd like to do. The reason I'd like to have this work with Swagger is that I can then publish the API design and documentation to something like Swagger Hub to support multi user collaboration. It would also be very cool to be able to roundtrip between proto and OpenAPI yaml... At this point I'd definitely settle for being able to go from proto to OpenApi - this project nearly gets there.

I got a test gRPC server with REST endpoints up and running. I add the relevant additions needed to add Swagger to my startup, which now looks like:

`
public class Startup
{
https://go.microsoft.com/fwlink/?LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpcHttpApi();
services.AddMvc();

        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        });
    }
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

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

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}`

It all compiles and runs OK, but when I go to the Swagger UI endpoint, the UI loads OK, but states that "No operations defined in spec!". Any ideas on how I can get Swagger to recognize the endpoints created by Microsoft.AspNetCore.Grpc.HttpApi ? Or could Swagger compatibility be added some time?

[JunTaoLuo]

We haven't tried GrpcHttpApi with Swagger so I'm not surprised it doesn't work right out of the box. It's something that we can investigate in the future though.

[profnimrod]

Yes, thanks... I wasn't surprised either and know it is not necessarily trivial to do that. There is a nice gRPC-swagger JAVA project that you might find of relevance... having the ability to insert optional Swagger annotations in the proto messages and services, and be able see both the gRPC and REST endpoints in the Swagger UI, would be very helpful indeed.

[JamesNK]

That .NET swagger library integrates into MVC. They would need to add custom support for gRPC+REST.

[JamesNK]

Sample that shows how to use gRPC HTTP API + Swagger

https://github.com/aspnet/AspLabs/tree/master/src/GrpcHttpApi/sample

[arttobe]

I followed this, but it is not working in dotnet 5
Has something changed?
The project compiles without error

[MichaelPeter]

Is it still planned to put this into Production?

Would look really forward in a way to write an documentation in GRPC without having to setup a golang grpc-gateway.