docs: buf plugin example (#103)

I wanted to make it easier for people to understand how to use the api-linter as a buf plugin, so I created an example project using the bookstore example.proto (Which embarrassingly fails linting) and added an explanation to the docs.

I also updated some stale references and text in the docs which still referred to AIP pages.

Author: dv-stewarts

README.md

@@ -1,12 +1,14 @@
 # Google API Linter
 
 [![ci](https://github.com/aep-dev/api-linter/actions/workflows/ci.yaml/badge.svg)](https://github.com/aep-dev/api-linter/actions/workflows/ci.yaml)
-![latest release](https://img.shields.io/github/v/release/googleapis/api-linter)
-![go version](https://img.shields.io/github/go-mod/go-version/googleapis/api-linter)
+![latest release](https://img.shields.io/github/v/release/aep-dev/api-linter)
+![go version](https://img.shields.io/github/go-mod/go-version/aep-dev/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][].
+The API linter provides real-time checks for compliance with many of the API
+standards, documented using [API Enhancement Proposals][]. It operates on API
+surfaces defined in [protocol buffers][]. For APIs defined in 
+[OpenAPI specification][] an equivalent [OpenAPI specification linter][] is
+available.
 
 It identifies common mistakes and inconsistencies in API surfaces:
 
@@ -20,11 +22,11 @@ message GetBookRequest {
 
 When able, it also offers a suggestion for the correct fix.
 
-[_Read more ≫_](https://linter.aip.dev/)
+[_Read more ≫_](docs/index.md)
 
 ## Versioning
 
-The Google API linter does **not** follow semantic versioning. Semantic
+The AEP API linter does **not** follow semantic versioning. Semantic
 versioning is challenging for a tool like a linter because the addition or
 correction of virtually any rule is "breaking" (in the sense that a file that
 previously reported no problems may now do so).
@@ -45,7 +47,7 @@ being useful.
 
 ## Contributing
 
-If you are interested in contributing to the API linter, please review the [contributing guide](https://linter.aip.dev/contributing) to learn more.
+If you are interested in contributing to the API linter, please review the [contributing guide](https://aep.dev/contributing/) to learn more.
 
 ## License
 
@@ -54,4 +56,5 @@ This software is made available under the [Apache 2.0][] license.
 [apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
 [api improvement proposals]: https://aip.dev/
 [protocol buffers]: https://developers.google.com/protocol-buffers
-[rule documentation]: ./rules/index.md
+[OpenAPI specification]: https://www.openapis.org/
+[OpenAPI specification linter]: https://github.com/aep-dev/aep-openapi-linter

docs/index.md

@@ -1,15 +1,17 @@
 ---
 ---
 
-# Google API Linter
+# AEP API Linter
 
 ![ci](https://github.com/aep-dev/api-linter/workflows/ci/badge.svg)
 ![latest release](https://img.shields.io/github/v/release/googleapis/api-linter)
 ![go version](https://img.shields.io/github/go-mod/go-version/googleapis/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][].
+The API linter provides real-time checks for compliance with many of the API
+standards, documented using [API Enhancement Proposals][]. It operates on API
+surfaces defined in [protocol buffers][]. For APIs defined in
+[OpenAPI specification][] an equivalent [OpenAPI specification linter][] is
+available.
 
 It identifies common mistakes and inconsistencies in API surfaces:
 
@@ -43,9 +45,6 @@ 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
 
 ```sh
@@ -80,12 +79,51 @@ Usage of api-linter:
       --version                         Print version and exit.
 ```
 
+### Usage with Buf
+
+[Buf][] builds tooling to make schema-driven, Protobuf-based API development
+reliable and user-friendly for service producers and consumers.
+This includes the `buf lint` command, which can be used to lint Protobuf files.
+The API linter can be used as a plugin for `buf lint`.
+
+To install the plugin, run:
+
+```sh
+go install github.com/aep-dev/api-linter/cmd/buf-plugin-aep@latest
+```
+
+It will install `buf-plugin-aep` into your local Go binary directory
+`$HOME/go/bin`. Ensure that your operating system's `PATH` contains the Go
+binary directory.
+
+Then, integrate the following into your `buf.yaml` file:
+
+```yaml
+lint:
+  use:
+    - AEP
+plugins:
+  - plugin: buf-plugin-aep
+```
+
+Now, you can run `buf lint` to lint your Protobuf files against the AEP rules.
+
+An example of building and linting with Buf can be found in the
+[example](./example) directory.
+
+More information on using Buf to lint Protobuf files can be found in the
+[Buf lint documentation][].
+
 ## License
 
 This software is made available under the [Apache 2.0][] license.
 
 [apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
-[api improvement proposals]: https://aep.dev/
+[API Enhancement Proposals]: https://aep.dev/
 [configuration]: ./configuration.md
 [protocol buffers]: https://developers.google.com/protocol-buffers
 [rule documentation]: ./rules/index.md
+[OpenAPI specification]: https://www.openapis.org/
+[OpenAPI specification linter]: https://github.com/aep-dev/aep-openapi-linter
+[Buf]: https://buf.build/
+[Buf lint documentation]: https://buf.build/docs/lint/overview/

example/.gitignore

@@ -0,0 +1,5 @@
+# Buf
+buf.lock
+
+# Generated code
+gen/

example/buf.gen.yaml

@@ -0,0 +1,11 @@
+version: v2
+managed:
+  enabled: true
+plugins:
+  - remote: buf.build/grpc/java:v1.69.0
+    out: gen
+  # dependencies
+  - remote: buf.build/protocolbuffers/java:v29.1
+    out: gen
+inputs:
+  - directory: proto

example/buf.yaml

@@ -0,0 +1,12 @@
+# For details on buf.yaml configuration, visit https://buf.build/docs/configuration/v2/buf-yaml
+version: v2
+modules:
+  - path: proto
+deps:
+  - buf.build/googleapis/googleapis
+lint:
+  use:
+    - AEP
+plugins:
+  - plugin: buf-plugin-aep
+