surface google.api.resource patterns in documentation

[codyoss]

A common issue people run into when using our clients is not properly formatting resource handles. In lieu of the api documentation being improved across thousands of RPC I wonder if you we just surface some of the formatting that is specified in the binding both in the docs and in samples we generate.

Related: googleapis/google-cloud-go#8237

[noahdietz]

Renamed the issue to focus on the google.api.resource patterns, which users input and end up in HTTP paths

The aspect of an HTTP path that the user provides input to (unknowingly) is the resource name that is inserted as a path variable. For example, with the following proto:

rpc GetBook (GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=books/*}"
  };
}

message GetBookRequest {
  string name = 1 [(google.api.resource_reference).type = "library.googleapis.com/Book"];
}

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };

  string name = 1;
}

The user will need to populate the GetBookRequest.name with something that resembles a Book name i.e. books/{book} e.g. `"books/the-hobbit", which will end up being used as part of the HTTP path if REST is chosen as a transport. Note: The same formatting requirements apply to gRPC requests, but aren't used in creating the request.

We can definitely improve this situation. Here are a few ideas for the generator:

• Include accepted formats per-field in method comments: If a request message contains a field representing a resource name, the acceptable patterns must be listed out in a comment on the method using that request message
• Include accepted formats per-field in method example_test code: The example_test snippets that end up in GoDoc examples can also have that same comment stating the accepted format for a field (maybe even generate an example like Name: "books/<BOOK_ID_HERE>", with the other supported patterns as a comment)
• Include accepted formats per-field in standalone snippets: Do the above but also in the standalone snippet files

[quartzmo]

I discussed this with @amanda-tarafa, who approves the addition to the snippets and will also review the PR.