Fix grpc-ecosystem#1117: Support response examples.

Add support for examples in operation annotation responses. Merge custom response data into the default 200 response.
paxosglobal · Jan 22, 2020 · a086fed · a086fed
1 parent 4cb25e1
commit a086fed
Show file tree

Hide file tree

Showing 8 changed files with 425 additions and 351 deletions.
diff --git a/examples/clients/abe/api/swagger.yaml b/examples/clients/abe/api/swagger.yaml
@@ -75,6 +75,9 @@ paths:
       responses:
         200:
           description: "A successful response."
+          examples:
+            application/json:
+              value: "the input value"
           schema:
             $ref: "#/definitions/subStringMessage"
         403:
@@ -1560,6 +1563,9 @@ paths:
       responses:
         200:
           description: "A successful response."
+          examples:
+            application/json:
+              value: "the input value"
           schema:
             $ref: "#/definitions/subStringMessage"
         403:
@@ -1598,6 +1604,9 @@ paths:
       responses:
         200:
           description: "A successful response."
+          examples:
+            application/json:
+              value: "the input value"
           schema:
             $ref: "#/definitions/subStringMessage"
         403:
@@ -2191,8 +2200,6 @@ definitions:
     properties:
       value:
         type: "string"
-    example:
-      value: "value"
 externalDocs:
   description: "More about gRPC-Gateway"
   url: "https://github.com/grpc-ecosystem/grpc-gateway"

diff --git a/examples/proto/examplepb/a_bit_of_everything.pb.go b/examples/proto/examplepb/a_bit_of_everything.pb.go
diff --git a/examples/proto/examplepb/a_bit_of_everything.proto b/examples/proto/examplepb/a_bit_of_everything.proto
@@ -446,6 +446,15 @@ service ABitOfEverythingService {
 				url: "https://github.com/grpc-ecosystem/grpc-gateway";
 				description: "Find out more Echo";
 			}
+			responses: {
+				key: "200"
+				value: {
+					examples: {
+						key: "application/json"
+						value: '{"value": "the input value"}'
+					}
+				}
+			}
 			responses: {
 				key: "503";
 				value: {

diff --git a/examples/proto/examplepb/a_bit_of_everything.swagger.json b/examples/proto/examplepb/a_bit_of_everything.swagger.json
@@ -81,6 +81,11 @@
             "description": "A successful response.",
             "schema": {
               "$ref": "#/definitions/subStringMessage"
+            },
+            "examples": {
+              "application/json": {
+                "value": "the input value"
+              }
             }
           },
           "403": {
@@ -1830,6 +1835,11 @@
             "description": "A successful response.",
             "schema": {
               "$ref": "#/definitions/subStringMessage"
+            },
+            "examples": {
+              "application/json": {
+                "value": "the input value"
+              }
             }
           },
           "403": {
@@ -1880,6 +1890,11 @@
             "description": "A successful response.",
             "schema": {
               "$ref": "#/definitions/subStringMessage"
+            },
+            "examples": {
+              "application/json": {
+                "value": "the input value"
+              }
             }
           },
           "403": {

diff --git a/protoc-gen-swagger/genswagger/template.go b/protoc-gen-swagger/genswagger/template.go
@@ -944,9 +944,16 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 					}
 					if opts.Responses != nil {
 						for name, resp := range opts.Responses {
-							respObj := swaggerResponseObject{
-								Description: resp.Description,
-								Schema:      swaggerSchemaFromProtoSchema(resp.Schema, reg, customRefs, meth),
+							// Merge response data into default response if available.
+							respObj := operationObject.Responses[name]
+							if resp.Description != "" {
+								respObj.Description = resp.Description
+							}
+							if resp.Schema != nil {
+								respObj.Schema = swaggerSchemaFromProtoSchema(resp.Schema, reg, customRefs, meth)
+							}
+							if resp.Examples != nil {
+								respObj.Examples = swaggerExamplesFromProtoExamples(resp.Examples)
 							}
 							if resp.Extensions != nil {
 								exts, err := processExtensions(resp.Extensions)
@@ -1232,6 +1239,7 @@ func applyTemplate(p param) (*swaggerObject, error) {
 						respMap[k] = swaggerResponseObject{
 							Description: v.Description,
 							Schema:      swaggerSchemaFromProtoSchema(v.Schema, p.reg, customRefs, nil),
+							Examples:    swaggerExamplesFromProtoExamples(v.Examples),
 						}
 					}
 				}
@@ -1703,6 +1711,24 @@ func swaggerSchemaFromProtoSchema(s *swagger_options.Schema, reg *descriptor.Reg
 	return ret
 }
 
+func swaggerExamplesFromProtoExamples(in map[string]string) map[string]interface{} {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make(map[string]interface{})
+	for mimeType, exampleStr := range in {
+		switch mimeType {
+		case "application/json":
+			// JSON example objects are rendered raw.
+			out[mimeType] = json.RawMessage(exampleStr)
+		default:
+			// All other mimetype examples are rendered as strings.
+			out[mimeType] = exampleStr
+		}
+	}
+	return out
+}
+
 func protoJSONSchemaTypeToFormat(in []swagger_options.JSONSchema_JSONSchemaSimpleTypes) (string, string) {
 	if len(in) == 0 {
 		return "", ""

diff --git a/protoc-gen-swagger/genswagger/types.go b/protoc-gen-swagger/genswagger/types.go
@@ -167,8 +167,9 @@ type swaggerResponsesObject map[string]swaggerResponseObject
 
 // http://swagger.io/specification/#responseObject
 type swaggerResponseObject struct {
-	Description string              `json:"description"`
-	Schema      swaggerSchemaObject `json:"schema"`
+	Description string                 `json:"description"`
+	Schema      swaggerSchemaObject    `json:"schema"`
+	Examples    map[string]interface{} `json:"examples,omitempty"`
 
 	extensions []extension
 }