diff --git a/aspnetcore/grpc/json-transcoding-openapi.md b/aspnetcore/grpc/json-transcoding-openapi.md deleted file mode 100644 index deea09f3930e..000000000000 --- a/aspnetcore/grpc/json-transcoding-openapi.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Use OpenAPI with gRPC JSON transcoding ASP.NET Core apps -author: jamesnk -description: Learn how to configure gRPC JSON transcoding to generate OpenAPI. -monikerRange: '>= aspnetcore-7.0' -ms.author: wpickett -ms.date: 02/19/2025 -uid: grpc/json-transcoding-openapi ---- -# gRPC JSON transcoding documentation with Swagger / OpenAPI - -[!INCLUDE[](~/includes/not-latest-version.md)] - -By [James Newton-King](https://twitter.com/jamesnk) - -[OpenAPI (Swagger)](https://swagger.io/specification/) is a language-agnostic specification for describing REST APIs. gRPC JSON transcoding supports generating OpenAPI from transcoded RESTful APIs. The [`Microsoft.AspNetCore.Grpc.Swagger`](https://www.nuget.org/packages/Microsoft.AspNetCore.Grpc.Swagger) package: - -* Integrates gRPC JSON transcoding with [Swashbuckle](xref:tutorials/get-started-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](xref:grpc/json-transcoding#usage). -2. Add a package reference to [`Microsoft.AspNetCore.Grpc.Swagger`](https://www.nuget.org/packages/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[](~/grpc/json-transcoding-openapi/Program.cs?name=snippet_1&highlight=3-8,11-16)] - -[!INCLUDE[](~/includes/package-reference.md)] - -## 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 `true`. -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[](~/grpc/json-transcoding-openapi/Program2.cs?name=snippet_1&highlight=6-8)] - -To confirm that Swashbuckle is generating OpenAPI with descriptions for the RESTful gRPC services, start the app and navigate to the Swagger UI page: - -![Swagger UI](~/grpc/json-transcoding-openapi/static/swaggerui.png) - -## Additional resources - -* -* [OpenAPI homepage](https://www.openapis.org/) -* [`Swashbuckle.AspNetCore` GitHub repository](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) diff --git a/aspnetcore/grpc/json-transcoding-openapi/Program.cs b/aspnetcore/grpc/json-transcoding-openapi/Program.cs deleted file mode 100644 index 504cad51721b..000000000000 --- a/aspnetcore/grpc/json-transcoding-openapi/Program.cs +++ /dev/null @@ -1,23 +0,0 @@ -#region snippet_1 -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddGrpc().AddJsonTranscoding(); -builder.Services.AddGrpcSwagger(); -builder.Services.AddSwaggerGen(c => -{ - c.SwaggerDoc("v1", - new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" }); -}); - -var app = builder.Build(); -app.UseSwagger(); -if (app.Environment.IsDevelopment()) -{ - app.UseSwaggerUI(c => - { - c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); - }); -} -app.MapGrpcService(); - -app.Run(); -#endregion diff --git a/aspnetcore/grpc/json-transcoding-openapi/Program2.cs b/aspnetcore/grpc/json-transcoding-openapi/Program2.cs deleted file mode 100644 index b41abc57b44f..000000000000 --- a/aspnetcore/grpc/json-transcoding-openapi/Program2.cs +++ /dev/null @@ -1,27 +0,0 @@ -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddGrpc().AddJsonTranscoding(); -builder.Services.AddGrpcSwagger(); -#region snippet_1 -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); -}); -#endregion - -var app = builder.Build(); -app.UseSwagger(); -if (app.Environment.IsDevelopment()) -{ - app.UseSwaggerUI(c => - { - c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); - }); -} -app.MapGrpcService(); - -app.Run(); diff --git a/aspnetcore/grpc/json-transcoding-openapi/static/swaggerui.png b/aspnetcore/grpc/json-transcoding-openapi/static/swaggerui.png deleted file mode 100644 index 83e3ca17a6e5..000000000000 Binary files a/aspnetcore/grpc/json-transcoding-openapi/static/swaggerui.png and /dev/null differ diff --git a/aspnetcore/grpc/json-transcoding.md b/aspnetcore/grpc/json-transcoding.md index 7d46c00b986a..1bfacb5883cd 100644 --- a/aspnetcore/grpc/json-transcoding.md +++ b/aspnetcore/grpc/json-transcoding.md @@ -169,7 +169,6 @@ For installation and usage of grpc-gateway, see the [grpc-gateway README](https: ## Additional resources * -* * * diff --git a/aspnetcore/grpc/json-transcoding/includes/json-transcoding7.md b/aspnetcore/grpc/json-transcoding/includes/json-transcoding7.md index 88ae90facb99..7f58a1a57ae2 100644 --- a/aspnetcore/grpc/json-transcoding/includes/json-transcoding7.md +++ b/aspnetcore/grpc/json-transcoding/includes/json-transcoding7.md @@ -152,7 +152,6 @@ For installation and usage of grpc-gateway, see the [grpc-gateway README](https: ## Additional resources * -* * * diff --git a/aspnetcore/release-notes/aspnetcore-7.0.md b/aspnetcore/release-notes/aspnetcore-7.0.md index bdfc4ec347f6..d7dd7281d460 100644 --- a/aspnetcore/release-notes/aspnetcore-7.0.md +++ b/aspnetcore/release-notes/aspnetcore-7.0.md @@ -210,7 +210,7 @@ gRPC JSON transcoding is an extension for ASP.NET Core that creates RESTful JSON * ASP.NET Core gRPC apps to support both gRPC and RESTful JSON APIs without replicating functionality. * Experimental support for generating OpenAPI from transcoded RESTful APIs by integrating with [Swashbuckle](xref:tutorials/get-started-with-swashbuckle). -For more information, see [gRPC JSON transcoding in ASP.NET Core gRPC apps](xref:grpc/json-transcoding?view=aspnetcore-7.0) and . +For more information, see [gRPC JSON transcoding in ASP.NET Core gRPC apps](xref:grpc/json-transcoding?view=aspnetcore-7.0). ### gRPC health checks in ASP.NET Core diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 7791d06df57e..2388f94c8ddc 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -1407,8 +1407,6 @@ items: uid: grpc/json-transcoding - name: HTTP rules and JSON uid: grpc/json-transcoding-binding - - name: Swagger / OpenAPI - uid: grpc/json-transcoding-openapi - name: Configuration uid: grpc/configuration - name: Authentication and authorization