Skip to content

Commit b64e865

Browse files
miparnisarimiparnisari
committed
generate OpenAPI docs
1 parent 2f0fe3e commit b64e865

File tree

7 files changed

+3402
-30
lines changed

7 files changed

+3402
-30
lines changed

‎.github/workflows/lint.yaml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,19 @@ on:
1818
- "synchronize"
1919
- "reopened"
2020

21-
2221
jobs:
2322
lint:
2423
name: "Lint & Publish Draft/Branch"
2524
runs-on: "ubuntu-latest"
2625
steps:
2726
- uses: "actions/checkout@v4"
2827
- uses: "authzed/actions/yaml-lint@main"
29-
- uses: "bufbuild/buf-action@v1"
28+
- name: "Lint Buf"
29+
uses: "bufbuild/buf-action@v1"
3030
with:
3131
token: "${{ secrets.BUF_REGISTRY_TOKEN }}"
3232
breaking_against: "https://github.com/authzed/api.git#branch=main"
33+
- name: "Lint Swagger docs"
34+
uses: "swaggerexpert/swagger-editor-validate@264fd875d3c6e1bf65da1f0a63e095cbe41ffef3" # v1.5.1
35+
with:
36+
definition-file: "./docs/apidocs.swagger.json"

‎.pre-commit-config.yaml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
---
22
repos:
33
- repo: "https://github.com/bufbuild/buf"
4-
rev: "v1.47.2"
4+
rev: "v1.54.0"
55
hooks:
6+
- id: "buf-generate"
67
- id: "buf-lint"
8+
- id: "buf-format"
79
- repo: "https://github.com/adrienverge/yamllint.git"
8-
rev: "v1.29.0"
10+
rev: "v1.37.1"
911
hooks:
1012
- id: "yamllint"

‎CONTRIBUTING.md

Lines changed: 0 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -65,23 +65,5 @@ If you have already authored a commit that is missing the signed-off, you can am
6565

6666
[DCO]: /DCO
6767

68-
## Common tasks
6968

70-
### Linting Protobuf Definitions
7169

72-
All [Protobuf] code is managed using [buf].
73-
You can lint the definitions by executing:
74-
75-
```sh
76-
buf build && buf lint
77-
```
78-
79-
[Protobuf]: https://developers.google.com/protocol-buffers/
80-
[buf]: https://docs.buf.build/installation
81-
82-
## ⚠️ Warnings ⚠️
83-
84-
- 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.
85-
- `buf build` and `buf generate` do entirely different things.
86-
Building compiles definitions and ensures semantic validity.
87-
Generate builds and then produces actual source code according to `buf.gen.yaml`.

‎Makefile

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

‎README.md

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Authzed API
22

33
[![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)
4-
[![Docs](https://img.shields.io/badge/docs-authzed.com-%234B4B6C "Authzed Documentation")](https://docs.authzed.com)
4+
[![Docs](https://img.shields.io/badge/docs-authzed.com-%234B4B6C "Authzed Documentation")](https://authzed.com/docs)
55
[![Build Status](https://github.com/authzed/api/workflows/Lint/badge.svg "GitHub Actions")](https://github.com/authzed/api/actions)
66
[![Discord Server](https://img.shields.io/discord/844600078504951838?color=7289da&logo=discord "Discord Server")](https://authzed.com/discord)
77
[![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,13 @@ This project contains the definitions of [Protocol Buffers] used by Authzed.
1010

1111
[Buf] is used to distribute these definitions and generate source code from them.
1212

13-
You can find more info on [authentication], [HTTP/JSON API usage], and the [versioning and deprecation policy] in the [Authzed Docs].
13+
You can find more info on [HTTP API usage] in the [Authzed Docs].
1414

1515
See [CONTRIBUTING.md] for instructions on how to contribute and perform common tasks like building the project and running tests.
1616

1717
[Protocol Buffers]: https://developers.google.com/protocol-buffers/
1818
[Buf]: https://github.com/bufbuild/buf
19-
[authentication]: https://docs.authzed.com/reference/api#authentication
20-
[HTTP/JSON API usage]: https://docs.authzed.com/reference/api#alternative-httpjson-api
21-
[versioning and deprecation policy]: https://docs.authzed.com/reference/api#versioning--deprecation-policy
22-
[Authzed Docs]: https://docs.authzed.com
23-
[Authzed API Reference documentation]: https://docs.authzed.com/reference/api
19+
[HTTP API usage]: https://authzed.com/docs/spicedb/getting-started/client-libraries#http-clients
20+
[Authzed Docs]: https://authzed.com/docs
2421
[Buf Registry Authzed API repository]: https://buf.build/authzed/api/docs/main
25-
[CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md
22+
[CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md

‎buf.gen.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
version: "v1"
2+
managed:
3+
enabled: true
4+
go_package_prefix:
5+
default: "github.com/authzed/api/proto"
6+
except:
7+
- "buf.build/googleapis/googleapis"
8+
- "buf.build/envoyproxy/protoc-gen-validate"
9+
- "buf.build/grpc-ecosystem/grpc-gateway"
10+
plugins:
11+
- plugin: "buf.build/grpc-ecosystem/openapiv2:v2.26.3"
12+
out: "docs"
13+
opt:
14+
- "openapi_naming_strategy=simple"
15+
- "allow_merge=true"

0 commit comments

Comments
 (0)