generate OpenAPI docs

.github/workflows/lint.yaml

@@ -18,7 +18,6 @@ on:
       - "synchronize"
       - "reopened"
 
-
 jobs:
   lint:
     name: "Lint & Publish Draft/Branch"

.pre-commit-config.yaml

@@ -1,10 +1,12 @@
 ---
 repos:
   - repo: "https://github.com/bufbuild/buf"
-    rev: "v1.47.2"
+    rev: "v1.54.0"
     hooks:
+      - id: "buf-generate"
       - id: "buf-lint"
+      - id: "buf-format"
   - repo: "https://github.com/adrienverge/yamllint.git"
-    rev: "v1.29.0"
+    rev: "v1.37.1"
     hooks:
       - id: "yamllint"

CONTRIBUTING.md

@@ -65,23 +65,5 @@ If you have already authored a commit that is missing the signed-off, you can am
 
 [DCO]: /DCO
 
-## Common tasks
 
-### Linting Protobuf Definitions
 
-All [Protobuf] code is managed using [buf].
-You can lint the definitions by executing:
-
-```sh
-buf build && buf lint
-```
-
-[Protobuf]: https://developers.google.com/protocol-buffers/
-[buf]: https://docs.buf.build/installation
-
-## ⚠️ Warnings ⚠️
-
-- The `version` field found in various buf YAML configuration is actually schema of the YAML of the file and is not related to the version of the definitions.
-- `buf build` and `buf generate` do entirely different things.
-   Building compiles definitions and ensures semantic validity.
-   Generate builds and then produces actual source code according to `buf.gen.yaml`.

Makefile

@@ -0,0 +1,7 @@
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install dependencies
+	brew install pre-commit
+	brew install bufbuild/buf/buf
+	pre-commit install

README.md

@@ -1,25 +1,34 @@
 # Authzed API
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg "Apache 2.0 License")](https://www.apache.org/licenses/LICENSE-2.0.html)
-[![Docs](https://img.shields.io/badge/docs-authzed.com-%234B4B6C "Authzed Documentation")](https://docs.authzed.com)
+[![Docs](https://img.shields.io/badge/docs-authzed.com-%234B4B6C "Authzed Documentation")](https://authzed.com/docs)
 [![Build Status](https://github.com/authzed/api/workflows/Lint/badge.svg "GitHub Actions")](https://github.com/authzed/api/actions)
 [![Discord Server](https://img.shields.io/discord/844600078504951838?color=7289da&logo=discord "Discord Server")](https://authzed.com/discord)
 [![Twitter](https://img.shields.io/twitter/follow/authzed?color=%23179CF0&logo=twitter&style=flat-square "@authzed on Twitter")](https://twitter.com/authzed)
 
 This project contains the definitions of [Protocol Buffers] used by Authzed.
 
-[Buf] is used to distribute these definitions and generate source code from them.
+We use [Buf] to distribute these definitions and generate source code from them. The definitions are published in [Buf Registry Authzed API repository].
 
-You can find more info on [authentication], [HTTP/JSON API usage], and the [versioning and deprecation policy] in the [Authzed Docs].
+You can find more info on [HTTP API usage] and the [versioning and deprecation policy] in the [Authzed Docs].
 
-See [CONTRIBUTING.md] for instructions on how to contribute and perform common tasks like building the project and running tests.
+You can also use our [Postman collection] to explore the API.
+
+See [CONTRIBUTING.md] for instructions on how to contribute.
 
 [Protocol Buffers]: https://developers.google.com/protocol-buffers/
 [Buf]: https://github.com/bufbuild/buf
-[authentication]: https://docs.authzed.com/reference/api#authentication
-[HTTP/JSON API usage]: https://docs.authzed.com/reference/api#alternative-httpjson-api
-[versioning and deprecation policy]: https://docs.authzed.com/reference/api#versioning--deprecation-policy
-[Authzed Docs]: https://docs.authzed.com
-[Authzed API Reference documentation]: https://docs.authzed.com/reference/api
+[HTTP API usage]: https://authzed.com/docs/spicedb/getting-started/client-libraries#http-clients
+[Authzed Docs]: https://authzed.com/docs
+[versioning and deprecation policy]: https://authzed.com/blog/buf
+[Postman collection]: (https://www.postman.com/authzed/spicedb/collection/m26cqyc)
 [Buf Registry Authzed API repository]: https://buf.build/authzed/api/docs/main
 [CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md
+
+## Development
+
+You can run `mage` to see the available commands for development. We assume you have a Mac computer.
+
+## Warnings ⚠️
+
+- The `version` field found in various buf YAML configuration is actually schema of the YAML of the file and is not related to the version of the definitions.

buf.gen.yaml

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S buf generate --template
+---
+version: "v1"
+plugins:
+  - plugin: "buf.build/grpc-ecosystem/openapiv2:v2.26.3"
+    out: "docs"
+    opt:
+      - "openapi_naming_strategy=simple"
+      - "allow_merge=true"