github.com/googleapis/api-linter@v1.65.2/docs/index.md (about)

     1  ---
     2  ---
     3  
     4  # Google API Linter
     5  
     6  ![ci](https://github.com/googleapis/api-linter/workflows/ci/badge.svg)
     7  ![latest release](https://img.shields.io/github/v/release/googleapis/api-linter)
     8  ![go version](https://img.shields.io/github/go-mod/go-version/googleapis/api-linter)
     9  
    10  The API linter provides real-time checks for compliance with many of Google's
    11  API standards, documented using [API Improvement Proposals][]. It operates on
    12  API surfaces defined in [protocol buffers][].
    13  
    14  It identifies common mistakes and inconsistencies in API surfaces:
    15  
    16  ```proto
    17  // Incorrect.
    18  message GetBookRequest {
    19    // This is wrong; it should be spelled `name`.
    20    string book = 1;
    21  }
    22  ```
    23  
    24  When able, it also offers a suggestion for the correct fix.
    25  
    26  **Note:** Not every piece of AIP guidance is able to be expressed as lint rules
    27  (and some things that are able to be expressed may not be written yet). The
    28  linter should be used as a useful tool, but not as a substitute for reading and
    29  understanding API guidance.
    30  
    31  Each linter rule has its own [rule documentation][], and rules can be
    32  [configured][configuration] using a config file, or in a proto file itself.
    33  
    34  ## Installation
    35  
    36  To install `api-linter`, use `go install`:
    37  
    38  ```sh
    39  go install github.com/googleapis/api-linter/cmd/api-linter@latest
    40  ```
    41  
    42  It will install `api-linter` into your local Go binary directory
    43  `$HOME/go/bin`. Ensure that your operating system's `PATH` contains the Go
    44  binary directory.
    45  
    46  **Note:** For working in Google-internal source control, you should use the
    47  released binary `/google/bin/releases/api-linter/api-linter`.
    48  
    49  ## Usage
    50  
    51  ```sh
    52  api-linter proto_file1 proto_file2 ...
    53  ```
    54  
    55  To see the help message, run `api-linter -h`
    56  
    57  ```text
    58  Usage of api-linter:
    59        --config string                   The linter config file.
    60        --debug                           Run in debug mode. Panics will print stack.
    61        --descriptor-set-in stringArray   The file containing a FileDescriptorSet for searching proto imports.
    62                                          May be specified multiple times.
    63        --disable-rule stringArray        Disable a rule with the given name.
    64                                          May be specified multiple times.
    65        --enable-rule stringArray         Enable a rule with the given name.
    66                                          May be specified multiple times.
    67        --ignore-comment-disables         If set to true, disable comments will be ignored.
    68                                          This is helpful when strict enforcement of AIPs are necessary and
    69                                          proto definitions should not be able to disable checks.
    70        --list-rules                      Print the rules and exit.  Honors the output-format flag.
    71        --output-format string            The format of the linting results.
    72                                          Supported formats include "yaml", "json","github" and "summary" table.
    73                                          YAML is the default.
    74    -o, --output-path string              The output file path.
    75                                          If not given, the linting results will be printed out to STDOUT.
    76    -I, --proto-path stringArray          The folder for searching proto imports.
    77                                          May be specified multiple times; directories will be searched in order.
    78                                          The current working directory is always used.
    79        --set-exit-status                 Return exit status 1 when lint errors are found.
    80        --version                         Print version and exit.
    81  ```
    82  
    83  ## License
    84  
    85  This software is made available under the [Apache 2.0][] license.
    86  
    87  [apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
    88  [api improvement proposals]: https://aip.dev/
    89  [configuration]: ./configuration.md
    90  [protocol buffers]: https://developers.google.com/protocol-buffers
    91  [rule documentation]: ./rules/index.md