Google API Linter
The API linter provides real-time checks for compliance with many of Google’s API standards, documented using API Improvement Proposals. It operates on API surfaces defined in protocol buffers.
It identifies common mistakes and inconsistencies in API surfaces:
// Incorrect.
message GetBookRequest {
// This is wrong; it should be spelled `name`.
string book = 1;
}
When able, it also offers a suggestion for the correct fix.
Note: Not every piece of AIP guidance is able to be expressed as lint rules (and some things that are able to be expressed may not be written yet). The linter should be used as a useful tool, but not as a substitute for reading and understanding API guidance.
Each linter rule has its own rule documentation, and rules can be configured using a config file, or in a proto file itself.
Installation
To install api-linter
, use go install
:
go install github.com/googleapis/api-linter/cmd/api-linter@latest
It will install api-linter
into your local Go binary directory
$HOME/go/bin
. Ensure that your operating system’s PATH
contains the Go
binary directory.
Note: For working in Google-internal source control, you should use the
released binary /google/bin/releases/api-linter/api-linter
.
Usage
api-linter proto_file1 proto_file2 ...
To see the help message, run api-linter -h
Usage of api-linter:
--config string The linter config file.
--debug Run in debug mode. Panics will print stack.
--descriptor-set-in stringArray The file containing a FileDescriptorSet for searching proto imports.
May be specified multiple times.
--disable-rule stringArray Disable a rule with the given name.
May be specified multiple times.
--enable-rule stringArray Enable a rule with the given name.
May be specified multiple times.
--ignore-comment-disables If set to true, disable comments will be ignored.
This is helpful when strict enforcement of AIPs are necessary and
proto definitions should not be able to disable checks.
--list-rules Print the rules and exit. Honors the output-format flag.
--output-format string The format of the linting results.
Supported formats include "yaml", "json","github" and "summary" table.
YAML is the default.
-o, --output-path string The output file path.
If not given, the linting results will be printed out to STDOUT.
-I, --proto-path stringArray The folder for searching proto imports.
May be specified multiple times; directories will be searched in order.
The current working directory is always used.
--set-exit-status Return exit status 1 when lint errors are found.
--version Print version and exit.
License
This software is made available under the Apache 2.0 license.