From cff900e8f9e4b8f3a8f314f0f44eab222ebb870b Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Fri, 6 Nov 2015 18:38:31 +0000 Subject: Generated code for previous commit. --- csharp/src/Google.Protobuf/WellKnownTypes/Api.cs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'csharp/src/Google.Protobuf/WellKnownTypes/Api.cs') diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs index 2c64314d..899613f9 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs @@ -139,12 +139,14 @@ namespace Google.Protobuf.WellKnownTypes { /// outlined below. If the field is not empty, the version in the /// package name will be verified to be consistent with what is /// provided here. + /// /// The versioning schema uses [semantic /// versioning](http://semver.org) where the major version number /// indicates a breaking change and the minor version an additive, /// non-breaking change. Both version numbers are signals to users /// what to expect from different versions, and should be carefully /// chosen based on the product plan. + /// /// The major version is also reflected in the package name of the /// API, which must end in `v<major-version>`, as in /// `google.feature.v1`. For major versions 0 and 1, the suffix can @@ -629,16 +631,21 @@ namespace Google.Protobuf.WellKnownTypes { /// Declares an API to be included in this API. The including API must /// redeclare all the methods from the included API, but documentation /// and options are inherited as follows: + /// /// - If after comment and whitespace stripping, the documentation /// string of the redeclared method is empty, it will be inherited /// from the original method. + /// /// - Each annotation belonging to the service config (http, /// visibility) which is not set in the redeclared method will be /// inherited. + /// /// - If an http annotation is inherited, the path pattern will be /// modified as follows. Any version prefix will be replaced by the /// version of the including API plus the [root][] path if specified. + /// /// Example of a simple mixin: + /// /// package google.acl.v1; /// service AccessControl { /// // Get the underlying ACL object. @@ -646,25 +653,31 @@ namespace Google.Protobuf.WellKnownTypes { /// option (google.api.http).get = "/v1/{resource=**}:getAcl"; /// } /// } + /// /// package google.storage.v2; /// service Storage { /// // (-- see AccessControl.GetAcl --) /// rpc GetAcl(GetAclRequest) returns (Acl); + /// /// // Get a data record. /// rpc GetData(GetDataRequest) returns (Data) { /// option (google.api.http).get = "/v2/{resource=**}"; /// } /// } + /// /// Example of a mixin configuration: + /// /// apis: /// - name: google.storage.v2.Storage /// mixins: /// - name: google.acl.v1.AccessControl + /// /// The mixin construct implies that all methods in `AccessControl` are /// also declared with same name and request/response types in /// `Storage`. A documentation generator or annotation processor will /// see the effective `Storage.GetAcl` method after inherting /// documentation and annotations as follows: + /// /// service Storage { /// // Get the underlying ACL object. /// rpc GetAcl(GetAclRequest) returns (Acl) { @@ -672,15 +685,20 @@ namespace Google.Protobuf.WellKnownTypes { /// } /// ... /// } + /// /// Note how the version in the path pattern changed from `v1` to `v2`. + /// /// If the `root` field in the mixin is specified, it should be a /// relative path under which inherited HTTP paths are placed. Example: + /// /// apis: /// - name: google.storage.v2.Storage /// mixins: /// - name: google.acl.v1.AccessControl /// root: acls + /// /// This implies the following inherited HTTP annotation: + /// /// service Storage { /// // Get the underlying ACL object. /// rpc GetAcl(GetAclRequest) returns (Acl) { -- cgit v1.2.3