Conversation
OpenAPI仕様を3,011行の単一ファイルから23個のドメインベースファイルに分割しました。 主な変更: - openapi/paths/に12個のドメイン別エンドポイント定義を作成 - openapi/schemas/に10個のドメイン別スキーマ定義を作成 - Redocly CLIを使用した自動バンドルパイプラインを追加 - bundled.gen.yamlを自動生成ファイルとして明示（DO NOT EDITコメント付き） - Makefile、CLAUDE.md、README.mdを新構造に合わせて更新 - Lintエラーを修正（server URLのtrailing slash、enum型の不一致） 期待される効果: - ファイルサイズ削減: 3,011行 → 100-400行/ファイル - ナビゲーション向上: ドメイン名でファイルを直接特定可能 - マージコンフリクト削減: 異なるドメインの変更が独立したファイルに分離 - レビュー効率化: PRの変更範囲が明確化 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Kubosaka
requested review from
Chikuwa0141,
TkymHrt,
Wakai111,
Copilot and
hikahana
There was a problem hiding this comment.
Pull request overview
OpenAPI仕様を単一ファイルからドメイン別ファイルへ分割し、Redoclyでバンドルした bundled.gen.yaml を生成して各種ツール（Swagger UI / orval / oapi-codegen）から参照できるようにするPRです。
Changes:
- OpenAPI定義を
/openapi/paths/*.yamlと/openapi/schemas/*.yamlに分割 - Redocly CLI によるバンドル生成（
bundled.gen.yaml）をmake gen-apiに追加 - Swagger UI / orval の入力、及びドキュメントを新構造に合わせて更新
Reviewed changes
Copilot reviewed 27 out of 216 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| view/next-project/orval.config.js | orval の入力を bundled.gen.yaml に変更 |
| compose.swagger.yml | Swagger UI が bundled.gen.yaml を参照するよう更新 |
| README.md | OpenAPI分割構成と生成フローの説明を更新 |
| Makefile | Redocly bundle + 生成処理のパイプラインを追加、lint-apiターゲット追加 |
| CLAUDE.md | 分割後のOpenAPI構造と運用アナウンスを追加 |
| openapi/schemas/_shared.yaml | 共通スキーマ定義を追加 |
| openapi/schemas/activity.yaml | activityドメインのスキーマ定義を追加 |
| openapi/schemas/auth.yaml | authドメインのスキーマ定義を追加 |
| openapi/schemas/buy-report.yaml | buy-reportドメインのスキーマ定義を追加 |
| openapi/schemas/financial.yaml | financialドメインのスキーマ定義を追加 |
| openapi/schemas/festival-item.yaml | festival-itemドメインのスキーマ定義を追加 |
| openapi/schemas/organization.yaml | organizationドメインのスキーマ定義を追加 |
| openapi/schemas/sponsor.yaml | sponsorドメインのスキーマ定義を追加 |
| openapi/schemas/teacher.yaml | teacherドメインのスキーマ定義を追加 |
| openapi/schemas/user.yaml | userドメインのスキーマ定義を追加 |
| openapi/paths/activity.yaml | activity関連エンドポイント定義を追加 |
| openapi/paths/auth.yaml | auth関連エンドポイント定義を追加 |
| openapi/paths/buy-report.yaml | buy-report関連エンドポイント定義を追加 |
| openapi/paths/financial.yaml | financial関連エンドポイント定義を追加 |
| openapi/paths/festival-item.yaml | festival-item関連エンドポイント定義を追加 |
| openapi/paths/health.yaml | health checkエンドポイント定義を追加 |
| openapi/paths/organization.yaml | organization関連エンドポイント定義を追加 |
| openapi/paths/sponsor.yaml | sponsor関連エンドポイント定義を追加 |
| openapi/paths/teacher.yaml | teacher関連エンドポイント定義を追加 |
| openapi/paths/upload.yaml | uploadエンドポイント定義を追加 |
| openapi/paths/user.yaml | user関連エンドポイント定義を追加 |
| openapi/paths/year.yaml | year関連エンドポイント定義を追加 |
| application/json: | ||
| schema: | ||
| type: array | ||
| $ref: "../schemas/teacher.yaml#/components/schemas/teacher" |
There was a problem hiding this comment.
schema に type: array と $ref を同居させるのはOpenAPI的に不正です（配列の場合は items に $ref が必要）。type: array + items: { $ref: ... } の形に修正してください。
| $ref: "../schemas/teacher.yaml#/components/schemas/teacher" | |
| items: | |
| $ref: "../schemas/teacher.yaml#/components/schemas/teacher" |
| schema: | ||
| type: array | ||
| $ref: "../schemas/sponsor.yaml#/components/schemas/sponsor" |
There was a problem hiding this comment.
schema に type: array と $ref を同居させるのはOpenAPI的に不正です。配列を返すなら items に $ref を置く形に修正してください。
| schema: | ||
| type: array | ||
| $ref: "../schemas/sponsor.yaml#/components/schemas/sponsor" |
There was a problem hiding this comment.
schema の type: array と $ref の併記は不正です。加えて、/sponsors/{id} は通常1件取得に見えるため、意図が単一オブジェクトなら type: object（あるいは $ref のみ）にするなど、レスポンス形状も合わせて修正してください。
| - position | ||
| - department_id | ||
| - building | ||
| - room_number |
There was a problem hiding this comment.
required に room_number が含まれていますが、properties 側は room になっており不整合です。このままだとバリデーションやコード生成で必須プロパティが存在しない状態になります。required 側を room に合わせるか、properties 側の名前を揃えてください。
| - room_number | |
| - room |
| description: Filter by year. | ||
| required: true | ||
| schema: | ||
| type: string |
There was a problem hiding this comment.
/activities/details/{year} では year が integer なのに、こちらは string になっています。同一の意味のパスパラメータで型が食い違うとクライアント生成やバリデーションで破綻するので、どちらかに統一してください（恐らく integer）。
| type: string | |
| type: integer |
| @echo "Generating Go server code..." | ||
| @docker compose run --rm api oapi-codegen -config /openapi/config.yaml /openapi/bundled.gen.yaml | ||
|
|
||
| gen-front-api: ## フロント側API生成 |
There was a problem hiding this comment.
orval の入力が openapi/bundled.gen.yaml に変わったため、make gen-front-api を単独実行すると bundled.gen.yaml が存在せず失敗する可能性が高いです。gen-front-api を gen-api（または少なくとも bundle 生成）に依存させるなど、単体ターゲットとしても成立するようにしてください。
| gen-front-api: ## フロント側API生成 | |
| gen-front-api: gen-api ## フロント側API生成 |
| @echo "# DO NOT EDIT" > /tmp/header.txt | ||
| @echo "# This file is auto-generated from /openapi/openapi.yaml and related files." >> /tmp/header.txt | ||
| @echo "# To make changes, edit the source files in /openapi/paths/ and /openapi/schemas/" >> /tmp/header.txt | ||
| @echo "# and run 'make gen-api' to regenerate this file." >> /tmp/header.txt | ||
| @echo "" >> /tmp/header.txt | ||
| @cat openapi/bundled.gen.yaml >> /tmp/header.txt | ||
| @mv /tmp/header.txt openapi/bundled.gen.yaml |
There was a problem hiding this comment.
/tmp/header.txt を固定名で使うと、並列実行（CIでの並列ジョブや開発者の同時実行）で競合して内容が壊れる可能性があります。mktemp で一意な一時ファイルを作る、または openapi/.tmp 配下にPID付きファイル名で作成してから mv する形にしてください。
| @echo "# DO NOT EDIT" > /tmp/header.txt | |
| @echo "# This file is auto-generated from /openapi/openapi.yaml and related files." >> /tmp/header.txt | |
| @echo "# To make changes, edit the source files in /openapi/paths/ and /openapi/schemas/" >> /tmp/header.txt | |
| @echo "# and run 'make gen-api' to regenerate this file." >> /tmp/header.txt | |
| @echo "" >> /tmp/header.txt | |
| @cat openapi/bundled.gen.yaml >> /tmp/header.txt | |
| @mv /tmp/header.txt openapi/bundled.gen.yaml | |
| @HEADER_TMP=$$(mktemp); \ | |
| echo "# DO NOT EDIT" > $$HEADER_TMP; \ | |
| echo "# This file is auto-generated from /openapi/openapi.yaml and related files." >> $$HEADER_TMP; \ | |
| echo "# To make changes, edit the source files in /openapi/paths/ and /openapi/schemas/" >> $$HEADER_TMP; \ | |
| echo "# and run 'make gen-api' to regenerate this file." >> $$HEADER_TMP; \ | |
| echo "" >> $$HEADER_TMP; \ | |
| cat openapi/bundled.gen.yaml >> $$HEADER_TMP; \ | |
| mv $$HEADER_TMP openapi/bundled.gen.yaml |
| - name: bureau_id | ||
| in: query | ||
| description: bureau_d |
There was a problem hiding this comment.
パラメータ説明が bureau_d になっておりタイポに見えます。bureau_id など意図した表記に修正してください。
| delete: | ||
| tags: | ||
| - user | ||
| description: userの複数作成 |
There was a problem hiding this comment.
DELETE /users/delete の description が「userの複数作成」になっており、操作内容と矛盾しています（複数削除のはず）。ドキュメントとして誤解を招くので、削除であることが分かる説明に修正してください。
| description: userの複数作成 | |
| description: userの複数削除 |
| post: | ||
| tags: | ||
| - password_reset | ||
| description: トークンの称号 |
There was a problem hiding this comment.
description の「トークンの称号」は文言として不自然で、意味が伝わりにくいです（例: 「トークンの照合」や「トークンの検証」など）。意図に合わせて表現を修正してください。
| description: トークンの称号 | |
| description: トークンの検証 |
Summary of ChangesHello @Kubosaka, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request refactors the OpenAPI specification by splitting it into multiple domain-based files, aiming to improve maintainability, navigation, and reduce merge conflicts. It also introduces an automated bundling pipeline using Redocly CLI and updates the code generation process to use the bundled specification. Documentation has been updated to reflect these changes. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
| schema: | ||
| type: array | ||
| $ref: "../schemas/sponsor.yaml#/components/schemas/sponsor" |
There was a problem hiding this comment.
レスポンスのスキーマ定義が正しくありません。OpenAPI 3.0では、type: array と $ref を同じ階層に記述することはできません。
配列のアイテムとして $ref を指定するには、items プロパティを使用する必要があります。
schema:
type: array
items:
$ref: "../schemas/sponsor.yaml#/components/schemas/sponsor"この問題は GET /sponsors/{id} (L51-53) にも存在します。修正しないとコード生成が失敗する可能性があるため、クリティカルな問題です。
schema:
type: array
items:
$ref: "../schemas/sponsor.yaml#/components/schemas/sponsor"| schema: | ||
| type: array | ||
| $ref: "../schemas/sponsor.yaml#/components/schemas/sponsor" |
There was a problem hiding this comment.
GET /sponsors と同様に、こちらのレスポンススキーマも正しくありません。type: array と $ref を同じ階層に記述することはできません。
items プロパティを使って配列の要素を定義してください。
schema:
type: array
items:
$ref: "../schemas/sponsor.yaml#/components/schemas/sponsor" schema:
type: array
items:
$ref: "../schemas/sponsor.yaml#/components/schemas/sponsor"| schema: | ||
| type: array | ||
| $ref: "../schemas/teacher.yaml#/components/schemas/teacher" |
There was a problem hiding this comment.
GET /sponsors と同様に、こちらのレスポンススキーマも正しくありません。type: array と $ref を同じ階層に記述することはできません。
items プロパティを使って配列の要素を定義してください。
schema:
type: array
items:
$ref: "../schemas/teacher.yaml#/components/schemas/teacher" schema:
type: array
items:
$ref: "../schemas/teacher.yaml#/components/schemas/teacher"| - position | ||
| - department_id | ||
| - building | ||
| - room_number |
There was a problem hiding this comment.
teacher スキーマの required リストに room_number が含まれていますが、properties で定義されているプロパティ名は room です。
この不一致によりバリデーションエラーが発生します。room_number を room に修正してください。
- room| @echo "# DO NOT EDIT" > /tmp/header.txt | ||
| @echo "# This file is auto-generated from /openapi/openapi.yaml and related files." >> /tmp/header.txt | ||
| @echo "# To make changes, edit the source files in /openapi/paths/ and /openapi/schemas/" >> /tmp/header.txt | ||
| @echo "# and run 'make gen-api' to regenerate this file." >> /tmp/header.txt | ||
| @echo "" >> /tmp/header.txt | ||
| @cat openapi/bundled.gen.yaml >> /tmp/header.txt | ||
| @mv /tmp/header.txt openapi/bundled.gen.yaml |
There was a problem hiding this comment.
gen-apiターゲットでヘッダーを追記する際に、固定パスの /tmp/header.txt を使用していますが、これはCI環境などで並列実行された場合に競合する可能性があります。
より安全な方法として、mktempで一時ファイルを作成するか、以下のようにサブシェルとリダイレクトを利用してアトミックにファイルを置き換えることをお勧めします。
@( \
echo "# DO NOT EDIT"; \
echo "# This file is auto-generated from /openapi/openapi.yaml and related files."; \
echo "# To make changes, edit the source files in /openapi/paths/ and /openapi/schemas/"; \
echo "# and run 'make gen-api' to regenerate this file."; \
echo ""; \
cat openapi/bundled.gen.yaml \
) > openapi/bundled.gen.yaml.tmp && mv openapi/bundled.gen.yaml.tmp openapi/bundled.gen.yamlこれにより、より堅牢なスクリプトになります。
| description: Filter by year. | ||
| required: true | ||
| schema: | ||
| type: string |
There was a problem hiding this comment.
year パスパラメータの型に一貫性がありません。
GET /activities/details/{year}(L56) ではintegerGET /activities/filtered_details/{year}(L117) ではstring
となっています。
年度を表すのであれば、integerに統一するのが良いでしょう。
また、L114のdescriptionが英語になっている点も、他に合わせて日本語に修正するとより一貫性が高まります。
type: integer| delete: | ||
| tags: | ||
| - user | ||
| description: userの複数作成 |
There was a problem hiding this comment.
DELETE /users/delete の description が「userの複数作成」となっていますが、HTTPメソッドとエンドポイント名から「userの複数削除」が正しいと思われます。typoの修正をお勧めします。
description: userの複数削除| # content: | ||
| # "*/*": | ||
| # schema: | ||
| # type: array |
There was a problem hiding this comment.
GET /users のレスポンス content がコメントアウトされていますが、descriptionには「userの一覧を取得」と記載されています。
もし未実装のエンドポイントであれば、その旨を summary や description に明記するか、空の配列を返すスキーマを定義しておくと、API仕様書としての明確性が向上します。
例えば、以下のように定義できます。
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/user.yaml#/components/schemas/user'| type: array | ||
| example: [] | ||
| items: | ||
| type: number |
There was a problem hiding this comment.
destroyTeacherIDs スキーマの deleteIDs の items の type が number になっています。IDは通常整数なので、より厳密な integer 型を使用することをお勧めします。これにより、意図しない浮動小数点数が含まれるのを防ぐことができます。
type: integer| type: array | ||
| example: [] | ||
| items: | ||
| type: number |
There was a problem hiding this comment.
destroyUserIDs スキーマの deleteIDs の items の type が number になっています。IDは通常整数なので、より厳密な integer 型を使用することをお勧めします。これにより、意図しない浮動小数点数が含まれるのを防ぐことができます。
type: integer
| application/json: | ||
| schema: | ||
| type: string | ||
| $ref: "./paths/health.yaml#/paths/~1" |
There was a problem hiding this comment.
[imo]
ちょっと分割したファイルをさらに修正しないとだけど↓みたいにまとめた方がきれいめな感じする．
$ref: "./paths/health.yaml#/paths/~1"の ~1が/ になる仕様すっごい理解しづらいから可読性的にに直したいかも！
| $ref: "./paths/health.yaml#/paths/~1" | |
| $ref: "./paths/health.yaml#/health/" |
health:
get:
tags:
- health
description: health check
responses:
"200":
description: OK
content:
application/json:
schema:
type: string
| @echo "Bundling OpenAPI specification..." | ||
| @docker run --rm -v "$(PWD)/openapi:/spec" redocly/cli bundle /spec/openapi.yaml -o /spec/bundled.gen.yaml > /dev/null 2>&1 | ||
| @echo "# DO NOT EDIT" > /tmp/header.txt | ||
| @echo "# This file is auto-generated from /openapi/openapi.yaml and related files." >> /tmp/header.txt | ||
| @echo "# To make changes, edit the source files in /openapi/paths/ and /openapi/schemas/" >> /tmp/header.txt | ||
| @echo "# and run 'make gen-api' to regenerate this file." >> /tmp/header.txt | ||
| @echo "" >> /tmp/header.txt | ||
| @cat openapi/bundled.gen.yaml >> /tmp/header.txt |
There was a problem hiding this comment.
[ask]
この辺のechoっている？どうせ実行したとき見てない気がする
There was a problem hiding this comment.
これ生成ファイルのコメント書き込み処理やね
概要
OpenAPI仕様ファイル（openapi.yaml）を単一の3,011行ファイルから、23個のドメインベースファイルに分割しました。
これにより、保守性の向上、ナビゲーションの改善、マージコンフリクトの削減が期待できます。
主な変更点
新規作成ファイル
openapi/paths/- 12個のドメイン別エンドポイント定義openapi/schemas/- 10個のドメイン別スキーマ定義変更ファイル
openapi/openapi.yaml- メインエントリーポイントに変更（3,011行 → 160行）Makefile- Redocly CLIを使用した自動バンドルパイプライン追加compose.swagger.yml- bundled.gen.yamlを参照view/next-project/orval.config.js- bundled.gen.yamlを参照.gitignore- bundled.gen.yamlを除外対象に追加CLAUDE.md,README.md- 新しいOpenAPI構造に関するドキュメント更新自動生成ファイル
openapi/bundled.gen.yaml- Redocly CLIにより自動生成（DO NOT EDITコメント付き）修正した問題
true/false→"true"/"false"）期待される効果
技術的な変更
コード生成パイプライン
実行時の処理フロー：
bundled.gen.yamlファイル参照方法
相対パス参照を使用：
テスト項目
make gen-apiが正常に実行されるmake lint-apiでエラーが216個から216個（critical errors解消済み）備考
🤖 Generated with Claude Code