Add description, summary and tags fields in operationObject (swagger) (…

…#526) * Add Summary field (OperationObject -- Swagger) * Add Description field (OperationObject -- Swagger) * Add Tags field (OperationObject -- Swagger) * Add description field (openapiv2_operation) in examplepb * Add summary field (openapiv2_operation) in examplepb * Add tags field (openapiv2_operation) in examplepb * Swagger (JSON format) with summary, description and tags fields (openapiv2_operation)
grpc-ecosystem · Jan 21, 2018 · f09fb17 · f09fb17
1 parent 4529f7f
commit f09fb17
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 9 deletions.
diff --git a/examples/examplepb/a_bit_of_everything.proto b/examples/examplepb/a_bit_of_everything.proto
@@ -186,6 +186,10 @@ service ABitOfEverythingService {
 			}
 		};
 		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
+			description: "Description Echo";
+			summary: "Summary: Echo rpc";
+			tags: "echo service";
+			tags: "echo rpc";
 			external_docs: {
 				url: "https://github.com/grpc-ecosystem/grpc-gateway";
 				description: "Find out more Echo";

diff --git a/examples/examplepb/a_bit_of_everything.swagger.json b/examples/examplepb/a_bit_of_everything.swagger.json
@@ -51,8 +51,8 @@
     },
     "/v1/example/a_bit_of_everything/echo/{value}": {
       "get": {
-        "summary": "Echo allows posting a StringMessage value.",
-        "description": "It also exposes multiple bindings.\n\nThis makes it useful when validating that the OpenAPI v2 API\ndescription exposes documentation correctly on all paths\ndefined as additional_bindings in the proto.",
+        "summary": "Summary: Echo rpc",
+        "description": "Description Echo",
         "operationId": "Echo",
         "responses": {
           "200": {
@@ -71,7 +71,8 @@
           }
         ],
         "tags": [
-          "ABitOfEverythingService"
+          "echo service",
+          "echo rpc"
         ],
         "externalDocs": {
           "description": "Find out more Echo",
@@ -523,8 +524,8 @@
     },
     "/v2/example/echo": {
       "get": {
-        "summary": "Echo allows posting a StringMessage value.",
-        "description": "It also exposes multiple bindings.\n\nThis makes it useful when validating that the OpenAPI v2 API\ndescription exposes documentation correctly on all paths\ndefined as additional_bindings in the proto.",
+        "summary": "Summary: Echo rpc",
+        "description": "Description Echo",
         "operationId": "Echo3",
         "responses": {
           "200": {
@@ -543,16 +544,17 @@
           }
         ],
         "tags": [
-          "ABitOfEverythingService"
+          "echo service",
+          "echo rpc"
         ],
         "externalDocs": {
           "description": "Find out more Echo",
           "url": "https://github.com/grpc-ecosystem/grpc-gateway"
         }
       },
       "post": {
-        "summary": "Echo allows posting a StringMessage value.",
-        "description": "It also exposes multiple bindings.\n\nThis makes it useful when validating that the OpenAPI v2 API\ndescription exposes documentation correctly on all paths\ndefined as additional_bindings in the proto.",
+        "summary": "Summary: Echo rpc",
+        "description": "Description Echo",
         "operationId": "Echo2",
         "responses": {
           "200": {
@@ -573,7 +575,8 @@
           }
         ],
         "tags": [
-          "ABitOfEverythingService"
+          "echo service",
+          "echo rpc"
         ],
         "externalDocs": {
           "description": "Find out more Echo",

diff --git a/protoc-gen-swagger/genswagger/template.go b/protoc-gen-swagger/genswagger/template.go
@@ -638,6 +638,17 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 					// TODO(ivucica): this would be better supported by looking whether the method is deprecated in the proto file
 					operationObject.Deprecated = opts.Deprecated
 
+					if opts.Summary != "" {
+						operationObject.Summary = opts.Summary
+					}
+					if opts.Description != "" {
+						operationObject.Description = opts.Description
+					}
+					if len(opts.Tags) > 0 {
+						operationObject.Tags = make([]string, len(opts.Tags))
+						copy(operationObject.Tags, opts.Tags)
+					}
+
 					// TODO(ivucica): add remaining fields of operation object
 				}