protoc-gen-swagger: add example similar to AIP-133

This example illustrates that the `book_id` field is not converted into
a query string parameter in the generated swagger.json file.

examples/internal/clients/abe/BUILD.bazel

@@ -15,6 +15,8 @@ go_library(
         "model_examplepb_a_bit_of_everything.go",
         "model_examplepb_a_bit_of_everything_repeated.go",
         "model_examplepb_body.go",
+        "model_examplepb_book.go",
+        "model_examplepb_collection.go",
         "model_examplepb_numeric_enum.go",
         "model_examplepb_update_v2_request.go",
         "model_message_path_enum_nested_path_enum.go",

examples/internal/clients/abe/api/swagger.yaml

@@ -1527,6 +1527,49 @@ paths:
           description: "An unexpected error response"
           schema:
             $ref: "#/definitions/runtimeError"
+  /v1/{parent=publishers/*}/books:
+    post:
+      tags:
+      - "ABitOfEverythingService"
+      summary: "Create a book."
+      operationId: "ABitOfEverythingService_CreateBook"
+      parameters:
+      - name: "parent"
+        in: "path"
+        description: "The publisher in which to create the book.\n\nFormat: `publishers/{publisher}`\n\
+          \nExample: `publishers/1257894000000000000`"
+        required: true
+        type: "string"
+        x-exportParamName: "Parent"
+      - in: "body"
+        name: "body"
+        description: "The book to create."
+        required: true
+        schema:
+          $ref: "#/definitions/examplepbBook"
+        x-exportParamName: "Body"
+      responses:
+        200:
+          description: "A successful response."
+          schema:
+            $ref: "#/definitions/examplepbBook"
+        403:
+          description: "Returned when the user does not have permission to access\
+            \ the resource."
+          schema: {}
+        404:
+          description: "Returned when the resource does not exist."
+          schema:
+            type: "string"
+            format: "string"
+        418:
+          description: "I'm a teapot."
+          schema:
+            $ref: "#/definitions/examplepbNumericEnum"
+        default:
+          description: "An unexpected error response"
+          schema:
+            $ref: "#/definitions/runtimeError"
   /v2/example/a_bit_of_everything/{abe.uuid}:
     put:
       tags:
@@ -2240,6 +2283,26 @@ definitions:
     properties:
       name:
         type: "string"
+  examplepbBook:
+    type: "object"
+    properties:
+      name:
+        type: "string"
+        description: "The resource name of the book.\n\nFormat: `publishers/{publisher}/books/{book}`\n\
+          \nExample: `publishers/1257894000000000000/books/my-book`"
+      id:
+        type: "string"
+        description: "Output only. The book's ID."
+        readOnly: true
+      create_time:
+        type: "string"
+        format: "date-time"
+        description: "Output only. Creation time of the book."
+        readOnly: true
+    example:
+      create_time: "2000-01-23T04:56:07.000+00:00"
+      name: "name"
+      id: "id"
   examplepbNumericEnum:
     type: "string"
     description: "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE\

examples/internal/clients/abe/api_a_bit_of_everything_service.go

@@ -1262,6 +1262,154 @@ func (a *ABitOfEverythingServiceApiService) ABitOfEverythingServiceCreateBody(ct
 	return localVarReturnValue, localVarHttpResponse, nil
 }
 
+/* 
+ABitOfEverythingServiceApiService Create a book.
+ * @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
+ * @param parent The publisher in which to create the book.  Format: `publishers/{publisher}`  Example: `publishers/1257894000000000000`
+ * @param body The book to create.
+
+@return ExamplepbBook
+*/
+func (a *ABitOfEverythingServiceApiService) ABitOfEverythingServiceCreateBook(ctx context.Context, parent string, body ExamplepbBook) (ExamplepbBook, *http.Response, error) {
+	var (
+		localVarHttpMethod = strings.ToUpper("Post")
+		localVarPostBody   interface{}
+		localVarFileName   string
+		localVarFileBytes  []byte
+		localVarReturnValue ExamplepbBook
+	)
+
+	// create path and map variables
+	localVarPath := a.client.cfg.BasePath + "/v1/{parent=publishers/*}/books"
+	localVarPath = strings.Replace(localVarPath, "{"+"parent"+"}", fmt.Sprintf("%v", parent), -1)
+
+	localVarHeaderParams := make(map[string]string)
+	localVarQueryParams := url.Values{}
+	localVarFormParams := url.Values{}
+
+	// to determine the Content-Type header
+	localVarHttpContentTypes := []string{"application/json", "application/x-foo-mime"}
+
+	// set Content-Type header
+	localVarHttpContentType := selectHeaderContentType(localVarHttpContentTypes)
+	if localVarHttpContentType != "" {
+		localVarHeaderParams["Content-Type"] = localVarHttpContentType
+	}
+
+	// to determine the Accept header
+	localVarHttpHeaderAccepts := []string{"application/json", "application/x-foo-mime"}
+
+	// set Accept header
+	localVarHttpHeaderAccept := selectHeaderAccept(localVarHttpHeaderAccepts)
+	if localVarHttpHeaderAccept != "" {
+		localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
+	}
+	// body params
+	localVarPostBody = &body
+	if ctx != nil {
+		// API Key Authentication
+		if auth, ok := ctx.Value(ContextAPIKey).(APIKey); ok {
+			var key string
+			if auth.Prefix != "" {
+				key = auth.Prefix + " " + auth.Key
+			} else {
+				key = auth.Key
+			}
+			localVarHeaderParams["X-API-Key"] = key
+
+		}
+	}
+	r, err := a.client.prepareRequest(ctx, localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)
+	if err != nil {
+		return localVarReturnValue, nil, err
+	}
+
+	localVarHttpResponse, err := a.client.callAPI(r)
+	if err != nil || localVarHttpResponse == nil {
+		return localVarReturnValue, localVarHttpResponse, err
+	}
+
+	localVarBody, err := ioutil.ReadAll(localVarHttpResponse.Body)
+	localVarHttpResponse.Body.Close()
+	if err != nil {
+		return localVarReturnValue, localVarHttpResponse, err
+	}
+
+	if localVarHttpResponse.StatusCode < 300 {
+		// If we succeed, return the data, otherwise pass on to decode error.
+		err = a.client.decode(&localVarReturnValue, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
+		if err == nil { 
+			return localVarReturnValue, localVarHttpResponse, err
+		}
+	}
+
+	if localVarHttpResponse.StatusCode >= 300 {
+		newErr := GenericSwaggerError{
+			body: localVarBody,
+			error: localVarHttpResponse.Status,
+		}
+
+		if localVarHttpResponse.StatusCode == 200 {
+			var v ExamplepbBook
+			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
+				if err != nil {
+					newErr.error = err.Error()
+					return localVarReturnValue, localVarHttpResponse, newErr
+				}
+				newErr.model = v
+				return localVarReturnValue, localVarHttpResponse, newErr
+		}
+
+		if localVarHttpResponse.StatusCode == 403 {
+			var v interface{}
+			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
+				if err != nil {
+					newErr.error = err.Error()
+					return localVarReturnValue, localVarHttpResponse, newErr
+				}
+				newErr.model = v
+				return localVarReturnValue, localVarHttpResponse, newErr
+		}
+
+		if localVarHttpResponse.StatusCode == 404 {
+			var v string
+			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
+				if err != nil {
+					newErr.error = err.Error()
+					return localVarReturnValue, localVarHttpResponse, newErr
+				}
+				newErr.model = v
+				return localVarReturnValue, localVarHttpResponse, newErr
+		}
+
+		if localVarHttpResponse.StatusCode == 418 {
+			var v ExamplepbNumericEnum
+			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
+				if err != nil {
+					newErr.error = err.Error()
+					return localVarReturnValue, localVarHttpResponse, newErr
+				}
+				newErr.model = v
+				return localVarReturnValue, localVarHttpResponse, newErr
+		}
+
+		if localVarHttpResponse.StatusCode == 0 {
+			var v RuntimeError
+			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
+				if err != nil {
+					newErr.error = err.Error()
+					return localVarReturnValue, localVarHttpResponse, newErr
+				}
+				newErr.model = v
+				return localVarReturnValue, localVarHttpResponse, newErr
+		}
+
+		return localVarReturnValue, localVarHttpResponse, newErr
+	}
+
+	return localVarReturnValue, localVarHttpResponse, nil
+}
+
 /* 
 ABitOfEverythingServiceApiService
  * @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().

examples/internal/clients/abe/model_examplepb_book.go

@@ -0,0 +1,24 @@
+/*
+ * A Bit of Everything
+ *
+ * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
+ *
+ * API version: 1.0
+ * Contact: [email protected]
+ * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git)
+ */
+
+package abe
+
+import (
+	"time"
+)
+
+type ExamplepbBook struct {
+	// The resource name of the book.  Format: `publishers/{publisher}/books/{book}`  Example: `publishers/1257894000000000000/books/my-book`
+	Name string `json:"name,omitempty"`
+	// Output only. The book's ID.
+	Id string `json:"id,omitempty"`
+	// Output only. Creation time of the book.
+	CreateTime time.Time `json:"create_time,omitempty"`
+}

examples/internal/clients/abe/model_examplepb_collection.go

@@ -0,0 +1,24 @@
+/*
+ * A Bit of Everything
+ *
+ * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
+ *
+ * API version: 1.0
+ * Contact: [email protected]
+ * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git)
+ */
+
+package abe
+
+import (
+	"time"
+)
+
+type ExamplepbCollection struct {
+	// The resource name of the collection.  Format: `accounts/{account}/collections/{collection}`  Example: `accounts/1257894000000000000/collections/my-collection`
+	Name string `json:"name,omitempty"`
+	// Output only. The collection's ID.
+	Id string `json:"id,omitempty"`
+	// Output only. Creation time of the collection.
+	CreateTime time.Time `json:"create_time,omitempty"`
+}