github.com/googleapis/api-linter@v1.65.2/docs/rules/0123/resource-annotation.md (about)

     1  ---
     2  rule:
     3    aip: 123
     4    name: [core, '0123', resource-annotation]
     5    summary: Resource messages should be annotated with `google.api.resource`.
     6  permalink: /123/resource-annotation
     7  redirect_from:
     8    - /0123/resource-annotation
     9  ---
    10  
    11  # Resource annotation presence
    12  
    13  This rule enforces that top-level messages that appear to represent resources
    14  have a `google.api.resource` annotation, as described in [AIP-123][].
    15  
    16  ## Details
    17  
    18  This rule scans all top-level messages, and assumes that messages with a
    19   `string name` field are resources unless the message name ends with `Request`.
    20  For messages that are resources, it complains if the `google.api.resource`
    21  annotation is missing.
    22  
    23  ## Examples
    24  
    25  **Incorrect** code for this rule:
    26  
    27  ```proto
    28  // Incorrect.
    29  message Book {
    30    // A `google.api.resource` annotation should be here.
    31    string name = 1;
    32  }
    33  ```
    34  
    35  **Correct** code for this rule:
    36  
    37  ```proto
    38  // Correct.
    39  message Book {
    40    option (google.api.resource) = {
    41      type: "library.googleapis.com/Book"
    42      pattern: "publishers/{publisher}/books/{book}"
    43    };
    44  
    45    string name = 1;
    46  }
    47  ```
    48  
    49  ## Disabling
    50  
    51  If you need to violate this rule, use a leading comment above the message.
    52  
    53  ```proto
    54  // (-- api-linter: core::0123::resource-annotation=disabled
    55  //     aip.dev/not-precedent: We need to do this because reasons. --)
    56  message Book {
    57    string name = 1;
    58  }
    59  ```
    60  
    61  If you need to violate this rule for an entire file, place the comment at the
    62  top of the file.
    63  
    64  [aip-123]: http://aip.dev/123
    65  [aip.dev/not-precedent]: https://aip.dev/not-precedent