protoc-gen-swagger: add example similar to AIP-133 (#1514)

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,7 @@ 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_numeric_enum.go",
         "model_examplepb_update_v2_request.go",
         "model_message_path_enum_nested_path_enum.go",

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

@@ -708,6 +708,249 @@ paths:
         schema:
           $ref: "#/definitions/ABitOfEverythingNested"
         x-exportParamName: "Body"
+      - name: "uuid"
+        in: "query"
+        required: false
+        type: "string"
+        x-exportParamName: "Uuid"
+        x-optionalDataType: "String"
+      - name: "float_value"
+        in: "query"
+        description: "Float value field"
+        required: true
+        type: "number"
+        default: 0.2
+        format: "float"
+        x-exportParamName: "FloatValue"
+      - name: "double_value"
+        in: "query"
+        required: false
+        type: "number"
+        format: "double"
+        x-exportParamName: "DoubleValue"
+        x-optionalDataType: "Float64"
+      - name: "int64_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "int64"
+        x-exportParamName: "Int64Value"
+        x-optionalDataType: "String"
+      - name: "uint64_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "uint64"
+        x-exportParamName: "Uint64Value"
+        x-optionalDataType: "String"
+      - name: "int32_value"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int32"
+        x-exportParamName: "Int32Value"
+        x-optionalDataType: "Int32"
+      - name: "fixed64_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "uint64"
+        x-exportParamName: "Fixed64Value"
+        x-optionalDataType: "String"
+      - name: "fixed32_value"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int64"
+        x-exportParamName: "Fixed32Value"
+        x-optionalDataType: "Int64"
+      - name: "bool_value"
+        in: "query"
+        required: false
+        type: "boolean"
+        format: "boolean"
+        x-exportParamName: "BoolValue"
+        x-optionalDataType: "Bool"
+      - name: "bytes_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "byte"
+        x-exportParamName: "BytesValue"
+        x-optionalDataType: "String"
+      - name: "uint32_value"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int64"
+        x-exportParamName: "Uint32Value"
+        x-optionalDataType: "Int64"
+      - name: "enum_value"
+        in: "query"
+        description: " - ZERO: ZERO means 0\n - ONE: ONE means 1"
+        required: false
+        type: "string"
+        default: "ZERO"
+        enum:
+        - "ZERO"
+        - "ONE"
+        x-exportParamName: "EnumValue"
+        x-optionalDataType: "String"
+      - name: "path_enum_value"
+        in: "query"
+        required: false
+        type: "string"
+        default: "ABC"
+        enum:
+        - "ABC"
+        - "DEF"
+        x-exportParamName: "PathEnumValue"
+        x-optionalDataType: "String"
+      - name: "nested_path_enum_value"
+        in: "query"
+        required: false
+        type: "string"
+        default: "GHI"
+        enum:
+        - "GHI"
+        - "JKL"
+        x-exportParamName: "NestedPathEnumValue"
+        x-optionalDataType: "String"
+      - name: "sfixed32_value"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int32"
+        x-exportParamName: "Sfixed32Value"
+        x-optionalDataType: "Int32"
+      - name: "sfixed64_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "int64"
+        x-exportParamName: "Sfixed64Value"
+        x-optionalDataType: "String"
+      - name: "sint32_value"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int32"
+        x-exportParamName: "Sint32Value"
+        x-optionalDataType: "Int32"
+      - name: "sint64_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "int64"
+        x-exportParamName: "Sint64Value"
+        x-optionalDataType: "String"
+      - name: "repeated_string_value"
+        in: "query"
+        required: false
+        type: "array"
+        items:
+          type: "string"
+        collectionFormat: "multi"
+        x-exportParamName: "RepeatedStringValue"
+      - name: "oneof_string"
+        in: "query"
+        required: false
+        type: "string"
+        x-exportParamName: "OneofString"
+        x-optionalDataType: "String"
+      - name: "nonConventionalNameValue"
+        in: "query"
+        required: false
+        type: "string"
+        x-exportParamName: "NonConventionalNameValue"
+        x-optionalDataType: "String"
+      - name: "timestamp_value"
+        in: "query"
+        required: false
+        type: "string"
+        format: "date-time"
+        x-exportParamName: "TimestampValue"
+        x-optionalDataType: "Time"
+      - name: "repeated_enum_value"
+        in: "query"
+        description: "repeated enum value. it is comma-separated in query.\n\n - ZERO:\
+          \ ZERO means 0\n - ONE: ONE means 1"
+        required: false
+        type: "array"
+        items:
+          type: "string"
+          enum:
+          - "ZERO"
+          - "ONE"
+        collectionFormat: "multi"
+        x-exportParamName: "RepeatedEnumValue"
+      - name: "repeated_enum_annotation"
+        in: "query"
+        description: "Repeated numeric enum title. Repeated numeric enum description.\n\
+          \n - ZERO: ZERO means 0\n - ONE: ONE means 1"
+        required: false
+        type: "array"
+        items:
+          type: "string"
+          enum:
+          - "ZERO"
+          - "ONE"
+        collectionFormat: "multi"
+        x-exportParamName: "RepeatedEnumAnnotation"
+      - name: "enum_value_annotation"
+        in: "query"
+        description: "Numeric enum title. Numeric enum description.\n\n - ZERO: ZERO\
+          \ means 0\n - ONE: ONE means 1"
+        required: false
+        type: "string"
+        default: "ZERO"
+        enum:
+        - "ZERO"
+        - "ONE"
+        x-exportParamName: "EnumValueAnnotation"
+        x-optionalDataType: "String"
+      - name: "repeated_string_annotation"
+        in: "query"
+        description: "Repeated string title. Repeated string description."
+        required: false
+        type: "array"
+        items:
+          type: "string"
+        collectionFormat: "multi"
+        x-exportParamName: "RepeatedStringAnnotation"
+      - name: "nested_annotation.name"
+        in: "query"
+        description: "name is nested field."
+        required: false
+        type: "string"
+        x-exportParamName: "NestedAnnotationName"
+        x-optionalDataType: "String"
+      - name: "nested_annotation.amount"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int64"
+        x-exportParamName: "NestedAnnotationAmount"
+        x-optionalDataType: "Int64"
+      - name: "nested_annotation.ok"
+        in: "query"
+        description: "DeepEnum description.\n\n - FALSE: FALSE is false.\n - TRUE:\
+          \ TRUE is true."
+        required: false
+        type: "string"
+        default: "FALSE"
+        enum:
+        - "FALSE"
+        - "TRUE"
+        x-exportParamName: "NestedAnnotationOk"
+        x-optionalDataType: "String"
+      - name: "int64_override_type"
+        in: "query"
+        required: false
+        type: "integer"
+        format: "int64"
+        x-exportParamName: "Int64OverrideType"
+        x-optionalDataType: "Int64"
       responses:
         200:
           description: "A successful response."
@@ -1527,6 +1770,57 @@ 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"
+      - name: "book_id"
+        in: "query"
+        description: "The ID to use for the book.\n\nThis must start with an alphanumeric\
+          \ character."
+        required: false
+        type: "string"
+        x-exportParamName: "BookId"
+        x-optionalDataType: "String"
+      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:
@@ -1544,6 +1838,15 @@ paths:
         schema:
           $ref: "#/definitions/examplepbABitOfEverything"
         x-exportParamName: "Body"
+      - name: "update_mask.paths"
+        in: "query"
+        description: "The set of field mask paths."
+        required: false
+        type: "array"
+        items:
+          type: "string"
+        collectionFormat: "multi"
+        x-exportParamName: "UpdateMaskPaths"
       responses:
         200:
           description: "A successful response."
@@ -1581,6 +1884,15 @@ paths:
         schema:
           $ref: "#/definitions/examplepbABitOfEverything"
         x-exportParamName: "Body"
+      - name: "update_mask.paths"
+        in: "query"
+        description: "The set of field mask paths."
+        required: false
+        type: "array"
+        items:
+          type: "string"
+        collectionFormat: "multi"
+        x-exportParamName: "UpdateMaskPaths"
       responses:
         200:
           description: "A successful response."
@@ -2240,6 +2552,28 @@ 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
+    description: "An example resource type from AIP-123 used to test the behavior\
+      \ described in\nthe CreateBookRequest message.\n\nSee: https://google.aip.dev/123"
+    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\