Conversation
Walkthroughドキュメント用の静的ページ docs/v2/index.html を新規追加し、Redoc で OpenAPI を表示。併せて docs/v2/openapi.json として OpenAPI v3.0.3 仕様（v2.0.0、/programs/v2/today.json のGETエンドポイント1本、スキーマ定義とエラーレスポンス含む）を新規追加。 Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant U as User Browser
participant H as docs/v2/index.html
participant R as Redoc (CDN)
participant S as Server
note over U,H: ページ読み込み
U->>H: GET /docs/v2/index.html
H-->>U: HTML (Redoc 初期化)
U->>R: Load Redoc script
note over R: Redoc 起動
R->>S: GET /docs/v2/openapi.json
S-->>R: 200 OpenAPI JSON
R-->>U: API ドキュメントをレンダリング
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (8)
docs/v2/openapi.json (5)
1-13: グローバル security の方針を明示してください（公開APIなら security: [] を定義）現状は security 未定義のため、ツール（Checkov: CKV_OPENAPI_4/5）が警告します。認証不要な公開APIである方針なら、明示的に
security: []を追加して意図を示すのが無難です。将来的に鍵やOAuth導入予定ならcomponents.securitySchemesも併記を。適用例（servers の直後に追加）:
"servers": [ { "url": "https://boatraceopenapi.github.io", "description": "Production server" } ], + "security": [],
16-41: operationId・tags・例を追加してクライアント生成と可読性を向上生成クライアントやドキュメントの品質向上のため、
operationId/tagsと 200 のサンプルを追加することを推奨します。"get": { - "summary": "GET /programs/v2/today.json", - "description": "GET operation for /programs/v2/today.json", + "operationId": "getProgramsToday", + "tags": ["Programs"], + "summary": "Get today's race programs", + "description": "今日の番組表(JSON)を取得します。", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoatraceOpenAPI" - } + }, + "examples": { + "empty": { + "summary": "No programs (例)", + "value": { "programs": [] } + } + } } } },
31-40: エラーレスポンスの JSON 形状を定義してください現在 400/404/500 は description のみで schema がありません。クライアント側が扱いやすいよう、共通
Errorスキーマを定義して参照させましょう。"400": { - "description": "Bad request" + "description": "Bad request", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } }, "404": { - "description": "Not found" + "description": "Not found", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } }, "500": { - "description": "Internal server error" + "description": "Internal server error", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } }"components": { "schemas": { + "Error": { + "type": "object", + "properties": { + "code": { "type": "string", "example": "BAD_REQUEST" }, + "message": { "type": "string", "example": "Invalid query" }, + "details": { "type": "object", "additionalProperties": true } + }, + "required": ["code", "message"], + "additionalProperties": false + },Also applies to: 44-201
46-53: スキーマの厳格化（additionalProperties, minItems）と再利用性の向上
- 主要オブジェクトに
additionalProperties: falseを付けて未知キーをはじくとデータ品質が上がります。- 配列に
minItems（可能ならmaxItemsも）を追加すると Lint（CKV_OPENAPI_21）回避と契約の明確化になります。Program/Boatを個別スキーマとして切り出し、$ref で参照すると保守性が上がります。最小差分例:
"BoatraceOpenAPI": { "type": "object", "properties": { "programs": { "type": "array", + "minItems": 0, "items": { - "type": "object", + "type": "object", "properties": { ... - } + }, + "additionalProperties": false } } }, "required": ["programs"], + "additionalProperties": false }（可能であれば
components.schemas.Programとcomponents.schemas.Boatを追加し、items: { "$ref": "#/components/schemas/Program" }、Program.properties.boats.itemsを"$ref": "#/components/schemas/Boat"に差し替え）Also applies to: 79-81, 151-179, 182-194, 196-201
3-7: メタ情報の拡充（任意）
info.licenseやinfo.contactを追加すると利用者に親切です。API の再配布条件や問い合わせ先を明示できます。docs/v2/index.html (3)
2-2: を指定してアクセシビリティを改善言語を明示してください（例: 日本語サイトなら
lang="ja"）。スクリーンリーダーや検索エンジンに有益です。-<html> +<html lang="ja">
3-7: モバイル対応とCDNのバージョン固定/SRI
- モバイル表示のため
meta viewportを追加。- ReDoc の CDN を
latestではなく固定バージョン＋SRIにすると将来の破壊的変更を回避できます（具体版は運用方針に合わせて選定）。<head> <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Boatrace Open API for Programs</title> - <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script> + <!-- 例: バージョン固定（SRIは実際の値に置換してください） --> + <script src="https://cdn.redoc.ly/redoc/v2.1.2/bundles/redoc.standalone.js" + integrity="sha384-...actual_hash..." + crossorigin="anonymous"></script> </head>
8-10: フォールバックを追加（任意）JS 無効時の案内を出すと UX が向上します。
<body> <redoc spec-url="openapi.json"></redoc> + <noscript>このページを表示するには JavaScript を有効にしてください。</noscript> </body>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/v2/index.html(1 hunks)docs/v2/openapi.json(1 hunks)
🧰 Additional context used
🪛 Checkov (3.2.334)
docs/v2/openapi.json
[HIGH] 1-202: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[HIGH] 1-202: Ensure that security operations is not empty.
(CKV_OPENAPI_5)
[MEDIUM] 49-194: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (2)
docs/v2/openapi.json (1)
8-16: 公開URLの実在を最終確認してください（GitHub Pages 配置との整合）
servers[0].urlとpathsの組み合わせで解決される実URLは
https://boatraceopenapi.github.io/programs/v2/today.jsonになります。プロジェクトページ運用（/programs/ プレフィックス）かどうかで変わるため、公開後に 200 が返ることを確認ください（root ページ運用なら paths 側の/programsを外す必要があります）。Also applies to: 15-41
docs/v2/index.html (1)
8-10: spec-url の相対パスは配置と一致するか確認
openapi.jsonがこの HTML と同じディレクトリにある前提です。/programs/v2/以外に配置する場合はパス調整が必要です。
| "race_closed_at": { | ||
| "type": "string" | ||
| }, |
There was a problem hiding this comment.
🛠️ Refactor suggestion
型の一貫性とバリデーション（特にパーセンテージ系）を強化
race_closed_atは日時ならformat: date-timeを付与。- パーセンテージ系は小数点の可能性が高いので
type: number＋minimum: 0/maximum: 100を推奨。 racer_assigned_motor_top_2_percentのみinteger、*_top_3_percentはnumberと不一致です。統一しましょう。
例（該当箇所のみ抜粋、他の % フィールドも同様に適用）:
"race_closed_at": {
- "type": "string"
+ "type": "string",
+ "format": "date-time"
}, "racer_assigned_motor_top_2_percent": {
- "type": "integer"
+ "type": "number",
+ "minimum": 0,
+ "maximum": 100
},
"racer_assigned_motor_top_3_percent": {
- "type": "number"
+ "type": "number",
+ "minimum": 0,
+ "maximum": 100
},
"racer_assigned_boat_top_2_percent": {
- "type": "number"
+ "type": "number",
+ "minimum": 0,
+ "maximum": 100
},
"racer_assigned_boat_top_3_percent": {
- "type": "number"
+ "type": "number",
+ "minimum": 0,
+ "maximum": 100
}Also applies to: 114-152
🤖 Prompt for AI Agents
In docs/v2/openapi.json around lines 64-66 and 114-152, the schema types and
validation for datetime and percentage fields are inconsistent: add "format:
date-time" to race_closed_at, change all percentage-like fields to type: number
with minimum: 0 and maximum: 100 (including racer_assigned_motor_top_2_percent
which is currently integer) so they are consistent and allow decimals, and keep
any truly integer-only fields explicitly typed integer if intended; update the
schema entries accordingly for all % fields in the indicated range.
There was a problem hiding this comment.
@shimomo 了解しました！細かい型の調整は後回しで問題ありませんね。現在の仕様書でも基本的な API ドキュメント機能は十分動作しますし、必要に応じて後で改善していけば良いと思います。
1 participant
試しに Redoc で API の仕様書を公開してみようと思います。
Summary by CodeRabbit