{"id":16595412,"url":"https://github.com/nissy-dev/protocol-buffers-to-openapi-sandbox","last_synced_at":"2025-10-29T12:30:30.186Z","repository":{"id":223224279,"uuid":"759373816","full_name":"nissy-dev/protocol-buffers-to-openapi-sandbox","owner":"nissy-dev","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-19T13:23:37.000Z","size":176,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-02-19T14:47:18.770Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nissy-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-02-18T12:20:26.000Z","updated_at":"2024-02-19T14:47:39.881Z","dependencies_parsed_at":"2024-02-19T14:47:28.235Z","dependency_job_id":"d4a2179c-1527-4ad3-98b3-34415495befe","html_url":"https://github.com/nissy-dev/protocol-buffers-to-openapi-sandbox","commit_stats":null,"previous_names":["nissy-dev/protocol-buffer-sandbox","nissy-dev/protocol-buffers-to-openapi-sandbox"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nissy-dev%2Fprotocol-buffers-to-openapi-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nissy-dev%2Fprotocol-buffers-to-openapi-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nissy-dev%2Fprotocol-buffers-to-openapi-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nissy-dev%2Fprotocol-buffers-to-openapi-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nissy-dev","download_url":"https://codeload.github.com/nissy-dev/protocol-buffers-to-openapi-sandbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219857764,"owners_count":16556055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T23:50:05.155Z","updated_at":"2025-10-29T12:30:29.840Z","avatar_url":"https://github.com/nissy-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protocol-buffers-to-openapi-sandbox\n\n## 使い方\n\n```sh\n// セットアップ\nnpm ci\n\n// Swagger UI の起動\ndocker compose up -d\n\n// swagger ファイルの更新とコードの自動生成\nnpm run generate\n```\n\n## やっていること\n\n- `protoc-gen-openapiv2` プラグインを使って、Protocol Buffer を Open API v2 の Spec に変換\n- `openapi-generator-cli` を使って、Open API v2 の Spec を v3 へ変換\n- `orval` を使って、API client とモックデータを生成\n\n## 所感\n\n- よかったところ\n  - Protocol Buffer の書き味がいい\n    - スキーマを書いているというより型を書いている感じに近い\n  - Buf によるツールやプラグイン管理の手軽さなどがいい\n    - プラグインの option なども yaml でかける\n      - protoc はそのまま使うと、コマンドライン引数がたくさんになって辛いことがある\n    - linter や formatter も提供してくれる\n  - モックデータも自動で生成できた\n    - MSW や Jest と組み合わせやすそう (モックサーバーが生成されるより)\n- 気になるところ\n  - Protocol Buffer を Open API に変換するツールが少ない\n    - v3 系でちゃんとメンテされているものがない\n    - v2 系だと `protoc-gen-openapiv2` が良さそうに見えるが、[v3 対応しなさそう](https://github.com/grpc-ecosystem/grpc-gateway/issues/441)\n    - v2 から v3 への変換ツールはあるが... 今後のことも考えるとあんまり持続可能ではなさそう\n  - OpenAPI 系のツールが v2 / v3 系でエコシステムが分断されている\n    - ツール群もメンテされるものを選ばないとマイグレーションコストがかかりそう\n    - コード生成系のツールで良さそうなものは、v3 対応しかしてない場合もある\n    - v3 の方が Swagger UI で生成される API docs の UI も良かった\n  - 変換のために扱うツールが増える\n    - 最初から Open API Spec を書いていれば、`orval` をインストールするだけで済んだ\n  - Protocol Buffer と Open API Spec の差異を理解する必要がある\n    - 実質学習コストが２倍になっているように感じる場面があった\n      - Protocol Buffer v3 は required の修飾子をサポートしていない\n        - 全てのフィールドは optional として扱われる\n        - [指定されなかったフィールドにはデフォルト値を入れるようになっている](https://protobuf.dev/programming-guides/proto3/#default)\n          - このため、コード生成上の型などは optional にはならない\n      - 必須フィールドにしたい場合は、[ここ](https://github.com/nissy-dev/protocol-buffer-sandbox/blob/07b97ac52ba7b97c2e981c7bf007cef92713a1ed/proto/sample/v1/post.proto#L60-L76)のように Protocol Buffer に JSON Schema を書いている\n      - Open API Spec を最初から書けばこの差を意識しなくて良いのに...と感じた\n\nOpen API の yaml を書くのが辛そうだが、最近だと [Spotlight](https://stoplight.io/) というツールを使うと GUI で編集できたりするらしく、こういったツールで解決はできそうかなという感じがした。Spotlight は、[mock サーバーを作成するツール](https://github.com/stoplightio/prism)や [Spec の linter](https://github.com/stoplightio/spectral) なども公開していて、かなり信頼できそう。\n\n## 参考資料\n\n- https://github.com/grpc-ecosystem/grpc-gateway\n  - `protoc-gen-openapiv2` が OpenAPI v2 Spec への変換ツール\n- https://github.com/solo-io/protoc-gen-openapi\n  - OpenAPI v3 Spec への変換ツール\n- protoc-gen-openapiv2 を使ってみた系の日本語資料\n  - [スキーマ定義言語 Protocol Buffers と protoc-gen-swagger を使って Web API のスキマを埋めよう](https://techblog.cartaholdings.co.jp/entry/protoc-gen-swagger)\n  - [protoc-gen-openapiv2を使用したprotoから自動生成されるswaggerのカスタマイズ](https://qiita.com/a-kym/items/cadc6c951f8a41fda02c)\n  - [gRPC-GatewayのAPIドキュメントを自動生成する](https://tech.yappli.io/entry/grpcgateway_swagger)\n  - [ProtobufでREST APIを快適に開発する方法のご紹介](https://tech.tier4.jp/entry/2022/02/02/160000)\n- https://orval.dev/\n  - OpenAPI Spec から API Client と mock データを作成するツール\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnissy-dev%2Fprotocol-buffers-to-openapi-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnissy-dev%2Fprotocol-buffers-to-openapi-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnissy-dev%2Fprotocol-buffers-to-openapi-sandbox/lists"}