diff --git a/examples/internal/clients/abe/BUILD.bazel b/examples/internal/clients/abe/BUILD.bazel index 87923dc67fe..6dfb81ccc5e 100644 --- a/examples/internal/clients/abe/BUILD.bazel +++ b/examples/internal/clients/abe/BUILD.bazel @@ -22,7 +22,6 @@ go_library( "model_nested_deep_enum.go", "model_pathenum_path_enum.go", "model_protobuf_any.go", - "model_protobuf_field_mask.go", "model_rpc_status.go", "model_sub_string_message.go", "response.go", diff --git a/examples/internal/clients/abe/api/swagger.yaml b/examples/internal/clients/abe/api/swagger.yaml index 488636ee327..da84cf33199 100644 --- a/examples/internal/clients/abe/api/swagger.yaml +++ b/examples/internal/clients/abe/api/swagger.yaml @@ -1838,15 +1838,15 @@ paths: schema: $ref: "#/definitions/examplepbABitOfEverything" x-exportParamName: "Body" - - name: "updateMask.paths" + - name: "updateMask" in: "query" - description: "The set of field mask paths." + description: "The paths to update." required: false type: "array" items: type: "string" collectionFormat: "multi" - x-exportParamName: "UpdateMaskPaths" + x-exportParamName: "UpdateMask" responses: 200: description: "A successful response." @@ -1884,15 +1884,15 @@ paths: schema: $ref: "#/definitions/examplepbABitOfEverything" x-exportParamName: "Body" - - name: "updateMask.paths" + - name: "updateMask" in: "query" - description: "The set of field mask paths." + description: "The paths to update." required: false type: "array" items: type: "string" collectionFormat: "multi" - x-exportParamName: "UpdateMaskPaths" + x-exportParamName: "UpdateMask" responses: 200: description: "A successful response." @@ -2551,7 +2551,10 @@ definitions: abe: $ref: "#/definitions/examplepbABitOfEverything" updateMask: - $ref: "#/definitions/protobufFieldMask" + type: "array" + description: "The paths to update." + items: + type: "string" title: "UpdateV2Request request for update includes the message and the update\ \ mask" pathenumPathEnum: @@ -2618,89 +2621,6 @@ definitions: \ custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\ \n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n\ \ \"value\": \"1.212s\"\n }" - protobufFieldMask: - type: "object" - properties: - paths: - type: "array" - description: "The set of field mask paths." - items: - type: "string" - title: "`FieldMask` represents a set of symbolic field paths, for example:" - description: "paths: \"f.a\"\n paths: \"f.b.d\"\n\nHere `f` represents a field\ - \ in some root message, `a` and `b`\nfields in the message found in `f`, and\ - \ `d` a field found in the\nmessage in `f.b`.\n\nField masks are used to specify\ - \ a subset of fields that should be\nreturned by a get operation or modified\ - \ by an update operation.\nField masks also have a custom JSON encoding (see\ - \ below).\n\n# Field Masks in Projections\n\nWhen used in the context of a projection,\ - \ a response message or\nsub-message is filtered by the API to only contain\ - \ those fields as\nspecified in the mask. For example, if the mask in the previous\n\ - example is applied to a response message as follows:\n\n f {\n a : 22\n\ - \ b {\n d : 1\n x : 2\n }\n y : 13\n }\n \ - \ z: 8\n\nThe result will not contain specific values for fields x,y and z\n\ - (their value will be set to the default, and omitted in proto text\noutput):\n\ - \n\n f {\n a : 22\n b {\n d : 1\n }\n }\n\nA repeated\ - \ field is not allowed except at the last position of a\npaths string.\n\nIf\ - \ a FieldMask object is not present in a get operation, the\noperation applies\ - \ to all fields (as if a FieldMask of all fields\nhad been specified).\n\nNote\ - \ that a field mask does not necessarily apply to the\ntop-level response message.\ - \ In case of a REST get operation, the\nfield mask applies directly to the response,\ - \ but in case of a REST\nlist operation, the mask instead applies to each individual\ - \ message\nin the returned resource list. In case of a REST custom method,\n\ - other definitions may be used. Where the mask applies will be\nclearly documented\ - \ together with its declaration in the API. In\nany case, the effect on the\ - \ returned resource/resources is required\nbehavior for APIs.\n\n# Field Masks\ - \ in Update Operations\n\nA field mask in update operations specifies which\ - \ fields of the\ntargeted resource are going to be updated. The API is required\n\ - to only change the values of the fields as specified in the mask\nand leave\ - \ the others untouched. If a resource is passed in to\ndescribe the updated\ - \ values, the API ignores the values of all\nfields not covered by the mask.\n\ - \nIf a repeated field is specified for an update operation, new values will\n\ - be appended to the existing repeated field in the target resource. Note that\n\ - a repeated field is only allowed in the last position of a `paths` string.\n\ - \nIf a sub-message is specified in the last position of the field mask for an\n\ - update operation, then new value will be merged into the existing sub-message\n\ - in the target resource.\n\nFor example, given the target message:\n\n f {\n\ - \ b {\n d: 1\n x: 2\n }\n c: [1]\n }\n\nAnd\ - \ an update message:\n\n f {\n b {\n d: 10\n }\n c:\ - \ [2]\n }\n\nthen if the field mask is:\n\n paths: [\"f.b\", \"f.c\"]\n\n\ - then the result will be:\n\n f {\n b {\n d: 10\n x: 2\n\ - \ }\n c: [1, 2]\n }\n\nAn implementation may provide options to\ - \ override this default behavior for\nrepeated and message fields.\n\nIn order\ - \ to reset a field's value to the default, the field must\nbe in the mask and\ - \ set to the default value in the provided resource.\nHence, in order to reset\ - \ all fields of a resource, provide a default\ninstance of the resource and\ - \ set all fields in the mask, or do\nnot provide a mask as described below.\n\ - \nIf a field mask is not present on update, the operation applies to\nall fields\ - \ (as if a field mask of all fields has been specified).\nNote that in the presence\ - \ of schema evolution, this may mean that\nfields the client does not know and\ - \ has therefore not filled into\nthe request will be reset to their default.\ - \ If this is unwanted\nbehavior, a specific service may require a client to\ - \ always specify\na field mask, producing an error if not.\n\nAs with get operations,\ - \ the location of the resource which\ndescribes the updated values in the request\ - \ message depends on the\noperation kind. In any case, the effect of the field\ - \ mask is\nrequired to be honored by the API.\n\n## Considerations for HTTP\ - \ REST\n\nThe HTTP kind of an update operation which uses a field mask must\n\ - be set to PATCH instead of PUT in order to satisfy HTTP semantics\n(PUT must\ - \ only be used for full updates).\n\n# JSON Encoding of Field Masks\n\nIn JSON,\ - \ a field mask is encoded as a single string where paths are\nseparated by a\ - \ comma. Fields name in each path are converted\nto/from lower-camel naming\ - \ conventions.\n\nAs an example, consider the following message declarations:\n\ - \n message Profile {\n User user = 1;\n Photo photo = 2;\n }\n\ - \ message User {\n string display_name = 1;\n string address =\ - \ 2;\n }\n\nIn proto a field mask for `Profile` may look as such:\n\n \ - \ mask {\n paths: \"user.display_name\"\n paths: \"photo\"\n }\n\ - \nIn JSON, the same mask is represented as below:\n\n {\n mask: \"user.displayName,photo\"\ - \n }\n\n# Field Masks and Oneof Fields\n\nField masks treat fields in oneofs\ - \ just as regular fields. Consider the\nfollowing message:\n\n message SampleMessage\ - \ {\n oneof test_oneof {\n string name = 4;\n SubMessage\ - \ sub_message = 9;\n }\n }\n\nThe field mask can be:\n\n mask {\n\ - \ paths: \"name\"\n }\n\nOr:\n\n mask {\n paths: \"sub_message\"\ - \n }\n\nNote that oneof type names (\"test_oneof\" in this case) cannot be\ - \ used in\npaths.\n\n## Field Mask Verification\n\nThe implementation of any\ - \ API method which has a FieldMask type field in the\nrequest should verify\ - \ the included field paths, and return an\n`INVALID_ARGUMENT` error if any path\ - \ is unmappable." rpcStatus: type: "object" properties: diff --git a/examples/internal/clients/abe/api_a_bit_of_everything_service.go b/examples/internal/clients/abe/api_a_bit_of_everything_service.go index f2fef84111d..ba53ba05660 100644 --- a/examples/internal/clients/abe/api_a_bit_of_everything_service.go +++ b/examples/internal/clients/abe/api_a_bit_of_everything_service.go @@ -3266,13 +3266,13 @@ ABitOfEverythingServiceApiService * @param abeUuid * @param body * @param optional nil or *ABitOfEverythingServiceUpdateV2Opts - Optional Parameters: - * @param "UpdateMaskPaths" (optional.Interface of []string) - The set of field mask paths. + * @param "UpdateMask" (optional.Interface of []string) - The paths to update. @return interface{} */ type ABitOfEverythingServiceUpdateV2Opts struct { - UpdateMaskPaths optional.Interface + UpdateMask optional.Interface } func (a *ABitOfEverythingServiceApiService) ABitOfEverythingServiceUpdateV2(ctx context.Context, abeUuid string, body ExamplepbABitOfEverything, localVarOptionals *ABitOfEverythingServiceUpdateV2Opts) (interface{}, *http.Response, error) { @@ -3292,8 +3292,8 @@ func (a *ABitOfEverythingServiceApiService) ABitOfEverythingServiceUpdateV2(ctx localVarQueryParams := url.Values{} localVarFormParams := url.Values{} - if localVarOptionals != nil && localVarOptionals.UpdateMaskPaths.IsSet() { - localVarQueryParams.Add("updateMask.paths", parameterToString(localVarOptionals.UpdateMaskPaths.Value(), "multi")) + if localVarOptionals != nil && localVarOptionals.UpdateMask.IsSet() { + localVarQueryParams.Add("updateMask", parameterToString(localVarOptionals.UpdateMask.Value(), "multi")) } // to determine the Content-Type header localVarHttpContentTypes := []string{"application/json", "application/x-foo-mime"} @@ -3424,13 +3424,13 @@ ABitOfEverythingServiceApiService * @param abeUuid * @param body * @param optional nil or *ABitOfEverythingServiceUpdateV22Opts - Optional Parameters: - * @param "UpdateMaskPaths" (optional.Interface of []string) - The set of field mask paths. + * @param "UpdateMask" (optional.Interface of []string) - The paths to update. @return interface{} */ type ABitOfEverythingServiceUpdateV22Opts struct { - UpdateMaskPaths optional.Interface + UpdateMask optional.Interface } func (a *ABitOfEverythingServiceApiService) ABitOfEverythingServiceUpdateV22(ctx context.Context, abeUuid string, body ExamplepbABitOfEverything, localVarOptionals *ABitOfEverythingServiceUpdateV22Opts) (interface{}, *http.Response, error) { @@ -3450,8 +3450,8 @@ func (a *ABitOfEverythingServiceApiService) ABitOfEverythingServiceUpdateV22(ctx localVarQueryParams := url.Values{} localVarFormParams := url.Values{} - if localVarOptionals != nil && localVarOptionals.UpdateMaskPaths.IsSet() { - localVarQueryParams.Add("updateMask.paths", parameterToString(localVarOptionals.UpdateMaskPaths.Value(), "multi")) + if localVarOptionals != nil && localVarOptionals.UpdateMask.IsSet() { + localVarQueryParams.Add("updateMask", parameterToString(localVarOptionals.UpdateMask.Value(), "multi")) } // to determine the Content-Type header localVarHttpContentTypes := []string{"application/json", "application/x-foo-mime"} diff --git a/examples/internal/clients/abe/model_examplepb_update_v2_request.go b/examples/internal/clients/abe/model_examplepb_update_v2_request.go index 95c9a710212..2c867a542d0 100644 --- a/examples/internal/clients/abe/model_examplepb_update_v2_request.go +++ b/examples/internal/clients/abe/model_examplepb_update_v2_request.go @@ -12,5 +12,6 @@ package abe type ExamplepbUpdateV2Request struct { Abe *ExamplepbABitOfEverything `json:"abe,omitempty"` - UpdateMask *ProtobufFieldMask `json:"updateMask,omitempty"` + // The paths to update. + UpdateMask []string `json:"updateMask,omitempty"` } diff --git a/examples/internal/clients/abe/model_protobuf_field_mask.go b/examples/internal/clients/abe/model_protobuf_field_mask.go deleted file mode 100644 index 5ca6567193e..00000000000 --- a/examples/internal/clients/abe/model_protobuf_field_mask.go +++ /dev/null @@ -1,17 +0,0 @@ -/* - * A Bit of Everything - * - * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen) - * - * API version: 1.0 - * Contact: none@example.com - * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) - */ - -package abe - -// paths: \"f.a\" paths: \"f.b.d\" Here `f` represents a field in some root message, `a` and `b` fields in the message found in `f`, and `d` a field found in the message in `f.b`. Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below). # Field Masks in Projections When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows: f { a : 22 b { d : 1 x : 2 } y : 13 } z: 8 The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output): f { a : 22 b { d : 1 } } A repeated field is not allowed except at the last position of a paths string. If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified). Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs. # Field Masks in Update Operations A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask. If a repeated field is specified for an update operation, new values will be appended to the existing repeated field in the target resource. Note that a repeated field is only allowed in the last position of a `paths` string. If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource. For example, given the target message: f { b { d: 1 x: 2 } c: [1] } And an update message: f { b { d: 10 } c: [2] } then if the field mask is: paths: [\"f.b\", \"f.c\"] then the result will be: f { b { d: 10 x: 2 } c: [1, 2] } An implementation may provide options to override this default behavior for repeated and message fields. In order to reset a field's value to the default, the field must be in the mask and set to the default value in the provided resource. Hence, in order to reset all fields of a resource, provide a default instance of the resource and set all fields in the mask, or do not provide a mask as described below. If a field mask is not present on update, the operation applies to all fields (as if a field mask of all fields has been specified). Note that in the presence of schema evolution, this may mean that fields the client does not know and has therefore not filled into the request will be reset to their default. If this is unwanted behavior, a specific service may require a client to always specify a field mask, producing an error if not. As with get operations, the location of the resource which describes the updated values in the request message depends on the operation kind. In any case, the effect of the field mask is required to be honored by the API. ## Considerations for HTTP REST The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates). # JSON Encoding of Field Masks In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions. As an example, consider the following message declarations: message Profile { User user = 1; Photo photo = 2; } message User { string display_name = 1; string address = 2; } In proto a field mask for `Profile` may look as such: mask { paths: \"user.display_name\" paths: \"photo\" } In JSON, the same mask is represented as below: { mask: \"user.displayName,photo\" } # Field Masks and Oneof Fields Field masks treat fields in oneofs just as regular fields. Consider the following message: message SampleMessage { oneof test_oneof { string name = 4; SubMessage sub_message = 9; } } The field mask can be: mask { paths: \"name\" } Or: mask { paths: \"sub_message\" } Note that oneof type names (\"test_oneof\" in this case) cannot be used in paths. ## Field Mask Verification The implementation of any API method which has a FieldMask type field in the request should verify the included field paths, and return an `INVALID_ARGUMENT` error if any path is unmappable. -type ProtobufFieldMask struct { - // The set of field mask paths. - Paths []string `json:"paths,omitempty"` -} diff --git a/examples/internal/proto/examplepb/a_bit_of_everything.pb.go b/examples/internal/proto/examplepb/a_bit_of_everything.pb.go index 75fd764b00c..7ccabe52462 100644 --- a/examples/internal/proto/examplepb/a_bit_of_everything.pb.go +++ b/examples/internal/proto/examplepb/a_bit_of_everything.pb.go @@ -769,7 +769,8 @@ type UpdateV2Request struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - Abe *ABitOfEverything `protobuf:"bytes,1,opt,name=abe,proto3" json:"abe,omitempty"` + Abe *ABitOfEverything `protobuf:"bytes,1,opt,name=abe,proto3" json:"abe,omitempty"` + // The paths to update. UpdateMask *field_mask.FieldMask `protobuf:"bytes,2,opt,name=update_mask,json=updateMask,proto3" json:"update_mask,omitempty"` } diff --git a/examples/internal/proto/examplepb/a_bit_of_everything.proto b/examples/internal/proto/examplepb/a_bit_of_everything.proto index 2810758db5c..b4aed2cf457 100644 --- a/examples/internal/proto/examplepb/a_bit_of_everything.proto +++ b/examples/internal/proto/examplepb/a_bit_of_everything.proto @@ -321,6 +321,7 @@ enum NumericEnum { // UpdateV2Request request for update includes the message and the update mask message UpdateV2Request { ABitOfEverything abe = 1; + // The paths to update. google.protobuf.FieldMask update_mask = 2; } diff --git a/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json b/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json index aee03ef53dc..4a0befa0e16 100644 --- a/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json +++ b/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json @@ -2171,8 +2171,8 @@ } }, { - "name": "updateMask.paths", - "description": "The set of field mask paths.", + "name": "updateMask", + "description": "The paths to update.", "in": "query", "required": false, "type": "array", @@ -2235,8 +2235,8 @@ } }, { - "name": "updateMask.paths", - "description": "The set of field mask paths.", + "name": "updateMask", + "description": "The paths to update.", "in": "query", "required": false, "type": "array", @@ -3104,7 +3104,11 @@ "$ref": "#/definitions/examplepbABitOfEverything" }, "updateMask": { - "$ref": "#/definitions/protobufFieldMask" + "type": "array", + "items": { + "type": "string" + }, + "description": "The paths to update." } }, "title": "UpdateV2Request request for update includes the message and the update mask" @@ -3132,20 +3136,6 @@ }, "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(\u0026foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := \u0026pb.Foo{...}\n any, err := ptypes.MarshalAny(foo)\n ...\n foo := \u0026pb.Foo{}\n if err := ptypes.UnmarshalAny(any, foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": \u003cstring\u003e,\n \"lastName\": \u003cstring\u003e\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" }, - "protobufFieldMask": { - "type": "object", - "properties": { - "paths": { - "type": "array", - "items": { - "type": "string" - }, - "description": "The set of field mask paths." - } - }, - "description": "paths: \"f.a\"\n paths: \"f.b.d\"\n\nHere `f` represents a field in some root message, `a` and `b`\nfields in the message found in `f`, and `d` a field found in the\nmessage in `f.b`.\n\nField masks are used to specify a subset of fields that should be\nreturned by a get operation or modified by an update operation.\nField masks also have a custom JSON encoding (see below).\n\n# Field Masks in Projections\n\nWhen used in the context of a projection, a response message or\nsub-message is filtered by the API to only contain those fields as\nspecified in the mask. For example, if the mask in the previous\nexample is applied to a response message as follows:\n\n f {\n a : 22\n b {\n d : 1\n x : 2\n }\n y : 13\n }\n z: 8\n\nThe result will not contain specific values for fields x,y and z\n(their value will be set to the default, and omitted in proto text\noutput):\n\n\n f {\n a : 22\n b {\n d : 1\n }\n }\n\nA repeated field is not allowed except at the last position of a\npaths string.\n\nIf a FieldMask object is not present in a get operation, the\noperation applies to all fields (as if a FieldMask of all fields\nhad been specified).\n\nNote that a field mask does not necessarily apply to the\ntop-level response message. In case of a REST get operation, the\nfield mask applies directly to the response, but in case of a REST\nlist operation, the mask instead applies to each individual message\nin the returned resource list. In case of a REST custom method,\nother definitions may be used. Where the mask applies will be\nclearly documented together with its declaration in the API. In\nany case, the effect on the returned resource/resources is required\nbehavior for APIs.\n\n# Field Masks in Update Operations\n\nA field mask in update operations specifies which fields of the\ntargeted resource are going to be updated. The API is required\nto only change the values of the fields as specified in the mask\nand leave the others untouched. If a resource is passed in to\ndescribe the updated values, the API ignores the values of all\nfields not covered by the mask.\n\nIf a repeated field is specified for an update operation, new values will\nbe appended to the existing repeated field in the target resource. Note that\na repeated field is only allowed in the last position of a `paths` string.\n\nIf a sub-message is specified in the last position of the field mask for an\nupdate operation, then new value will be merged into the existing sub-message\nin the target resource.\n\nFor example, given the target message:\n\n f {\n b {\n d: 1\n x: 2\n }\n c: [1]\n }\n\nAnd an update message:\n\n f {\n b {\n d: 10\n }\n c: [2]\n }\n\nthen if the field mask is:\n\n paths: [\"f.b\", \"f.c\"]\n\nthen the result will be:\n\n f {\n b {\n d: 10\n x: 2\n }\n c: [1, 2]\n }\n\nAn implementation may provide options to override this default behavior for\nrepeated and message fields.\n\nIn order to reset a field's value to the default, the field must\nbe in the mask and set to the default value in the provided resource.\nHence, in order to reset all fields of a resource, provide a default\ninstance of the resource and set all fields in the mask, or do\nnot provide a mask as described below.\n\nIf a field mask is not present on update, the operation applies to\nall fields (as if a field mask of all fields has been specified).\nNote that in the presence of schema evolution, this may mean that\nfields the client does not know and has therefore not filled into\nthe request will be reset to their default. If this is unwanted\nbehavior, a specific service may require a client to always specify\na field mask, producing an error if not.\n\nAs with get operations, the location of the resource which\ndescribes the updated values in the request message depends on the\noperation kind. In any case, the effect of the field mask is\nrequired to be honored by the API.\n\n## Considerations for HTTP REST\n\nThe HTTP kind of an update operation which uses a field mask must\nbe set to PATCH instead of PUT in order to satisfy HTTP semantics\n(PUT must only be used for full updates).\n\n# JSON Encoding of Field Masks\n\nIn JSON, a field mask is encoded as a single string where paths are\nseparated by a comma. Fields name in each path are converted\nto/from lower-camel naming conventions.\n\nAs an example, consider the following message declarations:\n\n message Profile {\n User user = 1;\n Photo photo = 2;\n }\n message User {\n string display_name = 1;\n string address = 2;\n }\n\nIn proto a field mask for `Profile` may look as such:\n\n mask {\n paths: \"user.display_name\"\n paths: \"photo\"\n }\n\nIn JSON, the same mask is represented as below:\n\n {\n mask: \"user.displayName,photo\"\n }\n\n# Field Masks and Oneof Fields\n\nField masks treat fields in oneofs just as regular fields. Consider the\nfollowing message:\n\n message SampleMessage {\n oneof test_oneof {\n string name = 4;\n SubMessage sub_message = 9;\n }\n }\n\nThe field mask can be:\n\n mask {\n paths: \"name\"\n }\n\nOr:\n\n mask {\n paths: \"sub_message\"\n }\n\nNote that oneof type names (\"test_oneof\" in this case) cannot be used in\npaths.\n\n## Field Mask Verification\n\nThe implementation of any API method which has a FieldMask type field in the\nrequest should verify the included field paths, and return an\n`INVALID_ARGUMENT` error if any path is unmappable.", - "title": "`FieldMask` represents a set of symbolic field paths, for example:" - }, "rpcStatus": { "type": "object", "properties": { diff --git a/protoc-gen-openapiv2/internal/genopenapi/template.go b/protoc-gen-openapiv2/internal/genopenapi/template.go index d2f4ea0472a..7366508e9d5 100644 --- a/protoc-gen-openapiv2/internal/genopenapi/template.go +++ b/protoc-gen-openapiv2/internal/genopenapi/template.go @@ -24,7 +24,16 @@ import ( "google.golang.org/protobuf/proto" ) +// wktSchemas are the schemas of well-known-types. +// The schemas must match with the behavior of the JSON unmarshaler in +// https://github.com/protocolbuffers/protobuf-go/blob/v1.25.0/encoding/protojson/well_known_types.go var wktSchemas = map[string]schemaCore{ + ".google.protobuf.FieldMask": { + Type: "array", + Items: (*openapiItemsObject)(&schemaCore{ + Type: "string", + }), + }, ".google.protobuf.Timestamp": { Type: "string", Format: "date-time", diff --git a/protoc-gen-openapiv2/internal/genopenapi/template_test.go b/protoc-gen-openapiv2/internal/genopenapi/template_test.go index 1fb9c9c591a..663dddcc87a 100644 --- a/protoc-gen-openapiv2/internal/genopenapi/template_test.go +++ b/protoc-gen-openapiv2/internal/genopenapi/template_test.go @@ -752,6 +752,123 @@ func TestMessageToQueryParametersWithJsonName(t *testing.T) { } } +func TestMessageToQueryParametersWellKnownTypes(t *testing.T) { + type test struct { + MsgDescs []*descriptorpb.DescriptorProto + Message string + Params []openapiParameterObject + } + + tests := []test{ + { + MsgDescs: []*descriptorpb.DescriptorProto{ + { + Name: proto.String("ExampleMessage"), + Field: []*descriptorpb.FieldDescriptorProto{ + { + Name: proto.String("a_field_mask"), + Type: descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(), + TypeName: proto.String(".google.protobuf.FieldMask"), + Number: proto.Int32(1), + }, + { + Name: proto.String("a_timestamp"), + Type: descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(), + TypeName: proto.String(".google.protobuf.Timestamp"), + Number: proto.Int32(2), + }, + }, + }, + { + Name: proto.String("FieldMask"), + Field: []*descriptorpb.FieldDescriptorProto{ + { + Name: proto.String("paths"), + Type: descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(), + Label: descriptorpb.FieldDescriptorProto_LABEL_REPEATED.Enum(), + Number: proto.Int32(1), + }, + }, + }, + { + Name: proto.String("Timestamp"), + Field: []*descriptorpb.FieldDescriptorProto{ + { + Name: proto.String("seconds"), + Type: descriptorpb.FieldDescriptorProto_TYPE_INT64.Enum(), + Number: proto.Int32(1), + }, + { + Name: proto.String("nanos"), + Type: descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(), + Number: proto.Int32(2), + }, + }, + }, + }, + Message: "ExampleMessage", + Params: []openapiParameterObject{ + { + Name: "a_field_mask", + In: "query", + Required: false, + Type: "array", + Items: &openapiItemsObject{ + Type: "string", + }, + CollectionFormat: "multi", + }, + { + Name: "a_timestamp", + In: "query", + Required: false, + Type: "string", + Format: "date-time", + }, + }, + }, + } + + for _, test := range tests { + reg := descriptor.NewRegistry() + reg.SetEnumsAsInts(true) + msgs := []*descriptor.Message{} + for _, msgdesc := range test.MsgDescs { + msgs = append(msgs, &descriptor.Message{DescriptorProto: msgdesc}) + } + file := descriptor.File{ + FileDescriptorProto: &descriptorpb.FileDescriptorProto{ + SourceCodeInfo: &descriptorpb.SourceCodeInfo{}, + Name: proto.String("example.proto"), + Package: proto.String("example"), + Dependency: []string{}, + MessageType: test.MsgDescs, + Service: []*descriptorpb.ServiceDescriptorProto{}, + }, + GoPkg: descriptor.GoPackage{ + Path: "example.com/path/to/example/example.pb", + Name: "example_pb", + }, + Messages: msgs, + } + reg.Load(&pluginpb.CodeGeneratorRequest{ + ProtoFile: []*descriptorpb.FileDescriptorProto{file.FileDescriptorProto}, + }) + + message, err := reg.LookupMsg("", ".example."+test.Message) + if err != nil { + t.Fatalf("failed to lookup message: %s", err) + } + params, err := messageToQueryParameters(message, reg, []descriptor.Parameter{}, nil) + if err != nil { + t.Fatalf("failed to convert message to query parameters: %s", err) + } + if !reflect.DeepEqual(params, test.Params) { + t.Errorf("expected %v, got %v", test.Params, params) + } + } +} + func TestApplyTemplateSimple(t *testing.T) { msgdesc := &descriptorpb.DescriptorProto{ Name: proto.String("ExampleMessage"), @@ -2147,6 +2264,49 @@ func TestSchemaOfField(t *testing.T) { }, }, }, + { + field: &descriptor.Field{ + FieldDescriptorProto: &descriptorpb.FieldDescriptorProto{ + Name: proto.String("wrapped_field"), + TypeName: proto.String(".google.protobuf.FieldMask"), + Type: descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(), + }, + }, + refs: make(refMap), + expected: schemaCore{ + Type: "array", + Items: &openapiItemsObject{ + Type: "string", + }, + }, + }, + { + field: &descriptor.Field{ + FieldDescriptorProto: &descriptorpb.FieldDescriptorProto{ + Name: proto.String("wrapped_field"), + TypeName: proto.String(".google.protobuf.Timestamp"), + Type: descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(), + }, + }, + refs: make(refMap), + expected: schemaCore{ + Type: "string", + Format: "date-time", + }, + }, + { + field: &descriptor.Field{ + FieldDescriptorProto: &descriptorpb.FieldDescriptorProto{ + Name: proto.String("wrapped_field"), + TypeName: proto.String(".google.protobuf.Duration"), + Type: descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(), + }, + }, + refs: make(refMap), + expected: schemaCore{ + Type: "string", + }, + }, { field: &descriptor.Field{ FieldDescriptorProto: &descriptorpb.FieldDescriptorProto{