Initial baseline: LaraBlog core with plugin commerce surface.

Captures the current working tree after theme slots, ArticleAccess, and the payment / paid-content plugins so subsequent work has a reviewable git history.
2026-08-12 01:15:38 +08:00
commit 263b98b218
337 changed files with 31393 additions and 0 deletions
@@ -0,0 +1,21 @@
+# API 文档
+
+- **OpenAPI 3**：[`openapi.yaml`](./openapi.yaml)
+- **实现**：`routes/api.php` → `/api/v1/*`
+- **阶段**：一期以**只读内容接口**为主，供小程序/H5/其他端拉取文章、分类、标签与站点信息
+
+## 快速试
+
+```bash
+curl -s http://larablog.test/api/v1/meta | jq
+curl -s http://larablog.test/api/v1/articles | jq
+curl -s http://larablog.test/api/v1/articles/1 | jq
+```
+
+## Swagger UI
+仓库不强制绑定某一 UI 实现。可任选：
+1. 把 `openapi.yaml` 导入 [Swagger Editor](https://editor.swagger.io/)
+2. 自建静态页引用 swagger-ui（二期可加 `l5-swagger` / `scramble`）
+
+## 鉴权（规划）
+写接口（发评论、会员、支付回调）将走 Bearer Token / 小程序 session；一期未开放写操作。
@@ -0,0 +1,83 @@
+openapi: 3.0.3
+info:
+  title: LaraBlog Public API
+  version: 1.0.0
+  description: |
+    面向小程序 / 第三方客户端的只读 JSON API（一期）。
+    Base path: `/api/v1`
+servers:
+  - url: /api/v1
+    description: Relative to APP_URL
+paths:
+  /meta:
+    get:
+      summary: 站点元信息
+      operationId: getMeta
+      responses:
+        '200':
+          description: OK
+  /articles:
+    get:
+      summary: 文章列表
+      operationId: listArticles
+      parameters:
+        - in: query
+          name: per_page
+          schema: { type: integer, minimum: 1, maximum: 50 }
+        - in: query
+          name: page
+          schema: { type: integer, minimum: 1 }
+      responses:
+        '200':
+          description: Paginated articles
+  /articles/{id}:
+    get:
+      summary: 文章详情（匿名；受限文仅试读）
+      description: |
+        匿名 API。免费文返回 `content` / `content_html`。
+        密码文与付费文不返回全文：`content` 为 null，`content_html`/`teaser_html` 为试读或摘要，
+        并带 `access.status`（`need_password` / `need_purchase` 等）。
+        已购/管理员全文仅 Web 登录会话可用（本期）。
+      operationId: getArticle
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: integer }
+      responses:
+        '200': { description: OK }
+        '404': { description: Not found }
+  /categories:
+    get:
+      summary: 分类列表
+      operationId: listCategories
+      responses:
+        '200': { description: OK }
+  /categories/{id}/articles:
+    get:
+      summary: 分类下文章
+      operationId: listCategoryArticles
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: integer }
+      responses:
+        '200': { description: OK }
+  /tags:
+    get:
+      summary: 标签列表
+      operationId: listTags
+      responses:
+        '200': { description: OK }
+  /tags/{name}/articles:
+    get:
+      summary: 标签下文章
+      operationId: listTagArticles
+      parameters:
+        - in: path
+          name: name
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }