Skip to content

Commit a4a0d28

Browse files
miparnisarimiparnisari
authored
Merge pull request #138 from authzed/generate-openapi
generate OpenAPI docs
2 parents 2f0fe3e + 0211a4a commit a4a0d28

File tree

10 files changed

+3459
-30
lines changed

10 files changed

+3459
-30
lines changed

‎.github/workflows/lint.yaml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ on:
1818
- "synchronize"
1919
- "reopened"
2020

21-
2221
jobs:
2322
lint:
2423
name: "Lint & Publish Draft/Branch"

‎.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: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,34 @@
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)
88

99
This project contains the definitions of [Protocol Buffers] used by Authzed.
1010

11-
[Buf] is used to distribute these definitions and generate source code from them.
11+
We use [Buf] to distribute these definitions and generate source code from them. The definitions are published in [Buf Registry Authzed API repository].
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] and the [versioning and deprecation policy] in the [Authzed Docs].
1414

15-
See [CONTRIBUTING.md] for instructions on how to contribute and perform common tasks like building the project and running tests.
15+
You can also use our [Postman collection] to explore the API.
16+
17+
See [CONTRIBUTING.md] for instructions on how to contribute.
1618

1719
[Protocol Buffers]: https://developers.google.com/protocol-buffers/
1820
[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
21+
[HTTP API usage]: https://authzed.com/docs/spicedb/getting-started/client-libraries#http-clients
22+
[Authzed Docs]: https://authzed.com/docs
23+
[versioning and deprecation policy]: https://authzed.com/blog/buf
24+
[Postman collection]: (https://www.postman.com/authzed/spicedb/collection/m26cqyc)
2425
[Buf Registry Authzed API repository]: https://buf.build/authzed/api/docs/main
2526
[CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md
27+
28+
## Development
29+
30+
You can run `mage` to see the available commands for development. We assume you have a Mac computer.
31+
32+
## Warnings ⚠️
33+
34+
- The `version` field found in various buf YAML configurations is actually the version of the schema of the YAML file and is not related to the version of the definitions.

‎buf.gen.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/usr/bin/env -S buf generate --template
2+
---
3+
version: "v1"
4+
plugins:
5+
- plugin: "buf.build/grpc-ecosystem/openapiv2:v2.26.3"
6+
out: "docs"
7+
opt:
8+
- "openapi_naming_strategy=simple"
9+
- "allow_merge=true"

0 commit comments

Comments
 (0)