Skip to content

feat: add Redoc API documentation #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shimomo merged 1 commit into from
Aug 31, 2025
Merged

feat: add Redoc API documentation #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/v2/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Boatrace Open API for Programs</title>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</head>
<body>
<redoc spec-url="openapi.json"></redoc>
</body>
</html>
202 changes: 202 additions & 0 deletions docs/v2/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
{
"openapi": "3.0.3",
"info": {
"title": "Boatrace Open API",
"description": "Boatrace Open API for Programs",
"version": "2.0.0"
},
"servers": [
{
"url": "https://boatraceopenapi.github.io",
"description": "Production server"
}
],
"paths": {
"/programs/v2/today.json": {
"get": {
"summary": "GET /programs/v2/today.json",
"description": "GET operation for /programs/v2/today.json",
"parameters": [],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BoatraceOpenAPI"
}
}
}
},
"400": {
"description": "Bad request"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
}
}
},
"components": {
"schemas": {
"BoatraceOpenAPI": {
"type": "object",
"properties": {
"programs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"race_date": {
"type": "string",
"format": "date-time"
},
"race_stadium_number": {
"type": "integer"
},
"race_number": {
"type": "integer"
},
"race_closed_at": {
"type": "string"
},
Comment on lines +64 to +66
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Aug 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ 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.

Copy link
Copy Markdown
Contributor Author

@shimomo shimomo Aug 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

細かい修正は後でやります。

Copy link
Copy Markdown

@coderabbitai coderabbitai bot Aug 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@shimomo 了解しました！細かい型の調整は後回しで問題ありませんね。現在の仕様書でも基本的な API ドキュメント機能は十分動作しますし、必要に応じて後で改善していけば良いと思います。

"race_grade_number": {
"type": "integer"
},
"race_title": {
"type": "string"
},
"race_subtitle": {
"type": "string"
},
"race_distance": {
"type": "integer"
},
"boats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"racer_boat_number": {
"type": "integer"
},
"racer_name": {
"type": "string"
},
"racer_number": {
"type": "integer"
},
"racer_class_number": {
"type": "integer"
},
"racer_branch_number": {
"type": "integer"
},
"racer_birthplace_number": {
"type": "integer"
},
"racer_age": {
"type": "integer"
},
"racer_weight": {
"type": "integer"
},
"racer_flying_count": {
"type": "integer"
},
"racer_late_count": {
"type": "integer"
},
"racer_average_start_timing": {
"type": "number"
},
"racer_national_top_1_percent": {
"type": "number"
},
"racer_national_top_2_percent": {
"type": "number"
},
"racer_national_top_3_percent": {
"type": "number"
},
"racer_local_top_1_percent": {
"type": "number"
},
"racer_local_top_2_percent": {
"type": "number"
},
"racer_local_top_3_percent": {
"type": "number"
},
"racer_assigned_motor_number": {
"type": "integer"
},
"racer_assigned_motor_top_2_percent": {
"type": "integer"
},
"racer_assigned_motor_top_3_percent": {
"type": "number"
},
"racer_assigned_boat_number": {
"type": "integer"
},
"racer_assigned_boat_top_2_percent": {
"type": "number"
},
"racer_assigned_boat_top_3_percent": {
"type": "number"
}
},
"required": [
"racer_boat_number",
"racer_name",
"racer_number",
"racer_class_number",
"racer_branch_number",
"racer_birthplace_number",
"racer_age",
"racer_weight",
"racer_flying_count",
"racer_late_count",
"racer_average_start_timing",
"racer_national_top_1_percent",
"racer_national_top_2_percent",
"racer_national_top_3_percent",
"racer_local_top_1_percent",
"racer_local_top_2_percent",
"racer_local_top_3_percent",
"racer_assigned_motor_number",
"racer_assigned_motor_top_2_percent",
"racer_assigned_motor_top_3_percent",
"racer_assigned_boat_number",
"racer_assigned_boat_top_2_percent",
"racer_assigned_boat_top_3_percent"
]
}
}
},
"required": [
"race_date",
"race_stadium_number",
"race_number",
"race_closed_at",
"race_grade_number",
"race_title",
"race_subtitle",
"race_distance",
"boats"
]
}
}
},
"required": [
"programs"
]
}
}
}
}