Track exported OpenAPI schema

.gitignore

@@ -5,4 +5,3 @@
 __pycache__/
 *.pyc
 data/
-openapi/

README.md

@@ -153,6 +153,8 @@ python scripts/export_openapi.py
 - `openapi/openapi.json`
 - `openapi/openapi.yaml`
 
+`openapi/` 当前纳入版本控制。接口发生变更时，应重新运行导出脚本并同步提交生成的 schema 文件。
+
 ## 容器启动
 
 1. 准备环境变量文件

openapi/openapi.json

@@ -0,0 +1,88 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Home Automation Backend (Python)",
+    "description": "Python rewrite skeleton for the home automation backend. This stage provides only the foundation for future module migration.",
+    "version": "0.1.0"
+  },
+  "paths": {
+    "/status": {
+      "get": {
+        "tags": [
+          "system"
+        ],
+        "summary": "Get Status",
+        "operationId": "get_status_status_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StatusResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/": {
+      "get": {
+        "tags": [
+          "pages"
+        ],
+        "summary": "Home",
+        "operationId": "home__get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/location/record": {
+      "post": {
+        "tags": [
+          "location"
+        ],
+        "summary": "Create Location Record",
+        "operationId": "create_location_record_location_record_post",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "StatusResponse": {
+        "properties": {
+          "status": {
+            "type": "string",
+            "title": "Status"
+          }
+        },
+        "type": "object",
+        "required": [
+          "status"
+        ],
+        "title": "StatusResponse"
+      }
+    }
+  }
+}

openapi/openapi.yaml

@@ -0,0 +1,56 @@
+openapi: 3.1.0
+info:
+  title: Home Automation Backend (Python)
+  description: Python rewrite skeleton for the home automation backend. This stage
+    provides only the foundation for future module migration.
+  version: 0.1.0
+paths:
+  /status:
+    get:
+      tags:
+      - system
+      summary: Get Status
+      operationId: get_status_status_get
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StatusResponse'
+  /:
+    get:
+      tags:
+      - pages
+      summary: Home
+      operationId: home__get
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            text/html:
+              schema:
+                type: string
+  /location/record:
+    post:
+      tags:
+      - location
+      summary: Create Location Record
+      operationId: create_location_record_location_record_post
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema: {}
+components:
+  schemas:
+    StatusResponse:
+      properties:
+        status:
+          type: string
+          title: Status
+      type: object
+      required:
+      - status
+      title: StatusResponse

scripts/export_openapi.py

@@ -1,13 +1,19 @@
+import json
+import sys
 from pathlib import Path
 
 import yaml
 
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
 from app.main import create_app
 
 
 def main() -> None:
     app = create_app()
-    output_dir = Path("openapi")
+    output_dir = PROJECT_ROOT / "openapi"
     output_dir.mkdir(parents=True, exist_ok=True)
 
     schema = app.openapi()
@@ -15,7 +21,7 @@ def main() -> None:
     json_path = output_dir / "openapi.json"
     yaml_path = output_dir / "openapi.yaml"
 
-    json_path.write_text(__import__("json").dumps(schema, ensure_ascii=False, indent=2), encoding="utf-8")
+    json_path.write_text(json.dumps(schema, ensure_ascii=False, indent=2), encoding="utf-8")
     yaml_path.write_text(yaml.safe_dump(schema, allow_unicode=True, sort_keys=False), encoding="utf-8")
 
     print(f"Wrote {json_path}")
@@ -24,4 +30,3 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
-