Apply additional Swagger properties using JSON.

Depends on PR #134. Reverts 562956f.
grpc-ecosystem · Oct 27, 2017 · 6ff06d8 · 6ff06d8
1 parent 1fd8ba6
commit 6ff06d8
Show file tree

Hide file tree

Showing 4 changed files with 133 additions and 3 deletions.
diff --git a/examples/examplepb/echo_service.pb.go b/examples/examplepb/echo_service.pb.go
diff --git a/examples/examplepb/echo_service.proto b/examples/examplepb/echo_service.proto
@@ -5,11 +5,39 @@ option go_package = "examplepb";
 //
 // Echo Service API consists of a single service which returns
 // a message.
+//
+// <!-- swagger extras start
+// {
+//   "info": {
+//     "title": "Echo Service",
+//     "version": "1.0",
+//     "contact": {
+//       "name": "gRPC-Gateway project",
+//       "url": "https://github.com/grpc-ecosystem/grpc-gateway",
+//       "email": "none@example.com"
+//     }
+//   },
+//   "host": "localhost",
+//   "externalDocs": {
+//     "url": "https://github.com/grpc-ecosystem/grpc-gateway",
+//     "description": "More about gRPC-Gateway"
+//   }
+// }
+// swagger extras end -->
 package grpc.gateway.examples.examplepb;
 
 import "google/api/annotations.proto";
 
 // SimpleMessage represents a simple message sent to the Echo service.
+//
+// <!-- swagger extras start
+// {
+//   "externalDocs": {
+//     "url": "http://github.com/grpc-ecosystem/grpc-gateway",
+//     "description": "Find out more about EchoService"
+//   }
+// }
+// swagger extras end -->
 message SimpleMessage {
 	// Id represents the message identifier.
 	string id = 1;
@@ -22,6 +50,15 @@ service EchoService {
 	//
 	// The message posted as the id parameter will also be
 	// returned.
+	//
+	// <!-- swagger extras start
+	// {
+	//   "externalDocs": {
+	//     "url": "http://github.com/grpc-ecosystem/grpc-gateway",
+	//     "description": "Find out more about EchoService"
+	//   }
+	// }
+	// swagger extras end -->
 	rpc Echo(SimpleMessage) returns (SimpleMessage) {
 		option (google.api.http) = {
 			post: "/v1/example/echo/{id}"

diff --git a/examples/examplepb/echo_service.swagger.json b/examples/examplepb/echo_service.swagger.json
@@ -3,8 +3,14 @@
   "info": {
     "title": "Echo Service",
     "description": "Echo Service API consists of a single service which returns\na message.",
-    "version": "version not set"
+    "version": "1.0",
+    "contact": {
+      "name": "gRPC-Gateway project",
+      "url": "https://github.com/gengo/grpc-gateway",
+      "email": "none@example.com"
+    }
   },
+  "host": "localhost",
   "schemes": [
     "http",
     "https"
@@ -39,7 +45,11 @@
         ],
         "tags": [
           "EchoService"
-        ]
+        ],
+        "externalDocs": {
+          "description": "Find out more about EchoService",
+          "url": "http://github.com/gengo/grpc-gateway"
+        }
       }
     },
     "/v1/example/echo/{id}/{num}": {

diff --git a/protoc-gen-swagger/genswagger/template.go b/protoc-gen-swagger/genswagger/template.go
@@ -14,6 +14,8 @@ import (
 	"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway/descriptor"
 )
 
+var swaggerExtrasRegexp = regexp.MustCompile(`(?s)^(.*[^\s])[\s]*<!-- swagger extras start(.*)swagger extras end -->[\s]*(.*)$`)
+
 func listEnumNames(enum *descriptor.Enum) (names []string) {
 	for _, value := range enum.GetValue() {
 		names = append(names, value.GetName())
@@ -631,20 +633,55 @@ func applyTemplate(p param) (string, error) {
 // updateSwaggerDataFromComments updates a Swagger object based on a comment
 // from the proto file.
 //
+// As a first step, a section matching:
+//
+//     <!-- swagger extras start.*swagger extras end-->
+//
+// where .* contains valid JSON will be stored for later processing, and then
+// removed from the passed string.
+// (Implementation note: Currently, the JSON gets immediately applied and
+// thus cannot override summary and description.)
+//
 // First paragraph of a comment is used for summary. Remaining paragraphs of a
 // comment are used for description. If 'Summary' field is not present on the
 // passed swaggerObject, the summary and description are joined by \n\n.
 //
 // If there is a field named 'Info', its 'Summary' and 'Description' fields
-// will be updated instead.
+// will be updated instead. (JSON always gets applied directly to the passed
+// object.)
 //
 // If there is no 'Summary', the same behavior will be attempted on 'Title',
 // but only if the last character is not a period.
+//
+// To apply additional Swagger properties, one can pass valid JSON as described
+// before. This JSON gets parsed and applied to the passed swaggerObject
+// directly. This lets users easily apply custom properties such as contact
+// details, API base path, et al.
 func updateSwaggerDataFromComments(swaggerObject interface{}, comment string) error {
 	if len(comment) == 0 {
 		return nil
 	}
 
+	// Find a section containing additional Swagger metadata.
+	matches := swaggerExtrasRegexp.FindStringSubmatch(comment)
+
+	if len(matches) > 0 {
+		// If found, before further processing, replace the
+		// comment with a version that does not contain the
+		// extras.
+		comment = matches[1]
+		if len(matches[3]) > 0 {
+			comment += "\n\n" + matches[3]
+		}
+
+		// Parse the JSON and apply it.
+		// TODO(ivucica): apply extras /after/ applying summary
+		// and description.
+		if err := json.Unmarshal([]byte(matches[2]), swaggerObject); err != nil {
+			return fmt.Errorf("error: %s, parsing: %s", err.Error(), matches[2])
+		}
+	}
+
 	// Figure out what to apply changes to.
 	swaggerObjectValue := reflect.ValueOf(swaggerObject)
 	infoObjectValue := swaggerObjectValue.Elem().FieldByName("Info")