generate OpenAPI docs

Author: miparnisari

.github/workflows/lint.yaml

@@ -18,7 +18,6 @@ on:
       - "synchronize"
       - "reopened"
 
-
 jobs:
   lint:
     name: "Lint & Publish Draft/Branch"
@@ -30,3 +29,6 @@ jobs:
         with:
           token: "${{ secrets.BUF_REGISTRY_TOKEN }}"
           breaking_against: "https://github.com/authzed/api.git#branch=main"
+      - uses: "swaggerexpert/swagger-editor-validate@264fd875d3c6e1bf65da1f0a63e095cbe41ffef3" # v1.5.1
+        with:
+          definition-file: "./docs/apidocs.swagger.json"

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,12 @@
+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
+	pre-commit install
+
+buf-gen: ## Generate API docs
+	./buf.gen.yaml
+
+lint: buf-gen ## Run linting
+	buf format -w
+	pre-commit run --all-files

README.md

@@ -1,7 +1,7 @@
 # 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)
@@ -10,16 +10,45 @@ This project contains the definitions of [Protocol Buffers] used by Authzed.
 
 [Buf] is used to distribute these definitions and generate source code from them.
 
-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 [authentication] and [HTTP API usage] in the [Authzed Docs].
 
 See [CONTRIBUTING.md] for instructions on how to contribute and perform common tasks like building the project and running tests.
 
 [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
 [Buf Registry Authzed API repository]: https://buf.build/authzed/api/docs/main
 [CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md
+
+## Common tasks
+
+Pre-requisite: Have `buf` installed.
+
+### 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`.
+
+### Generating OpenAPI Documentation
+
+Run:
+
+```bash
+./buf.gen.yaml
+```

buf.gen.yaml

@@ -0,0 +1,17 @@
+#!/usr/bin/env -S buf generate --template
+---
+version: "v1"
+managed:
+  enabled: true
+  go_package_prefix:
+    default: "github.com/authzed/api/proto"
+    except:
+      - "buf.build/googleapis/googleapis"
+      - "buf.build/envoyproxy/protoc-gen-validate"
+      - "buf.build/grpc-ecosystem/grpc-gateway"
+plugins:
+  - plugin: "buf.build/grpc-ecosystem/openapiv2:v2.26.3"
+    out: "docs"
+    opt:
+      - "openapi_naming_strategy=simple"
+      - "allow_merge=true"