87 lines
2.6 KiB
Markdown
87 lines
2.6 KiB
Markdown
# API 文档
|
||
|
||
对外 HTTP API，供小程序 / 第三方平台接入。Base URL：`https://your-domain.com/api`
|
||
|
||
- **交互式文档**（OpenAPI/Swagger 风格，Scramble 自动生成）：`GET /docs/api`
|
||
- **OpenAPI JSON**：`GET /docs/api.json`
|
||
- 认证：Bearer Token（Laravel Sanctum），仅 `/api/me` 需要
|
||
|
||
## 认证（可选）
|
||
|
||
```bash
|
||
# 生成 API Token
|
||
php artisan tinker --execute='$u = App\Models\User::where("email","you@example.com")->first(); dump($u->createToken("mini-program")->plainTextToken);'
|
||
```
|
||
|
||
请求头：`Authorization: Bearer <token>`
|
||
|
||
## 端点总览
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/site` | 站点信息 | 否 |
|
||
| GET | `/api/posts` | 文章列表（分页/筛选/搜索） | 否 |
|
||
| GET | `/api/posts/{slug}` | 文章详情（含渲染后 HTML） | 否 |
|
||
| GET | `/api/categories` | 分类列表 | 否 |
|
||
| GET | `/api/tags` | 标签列表（含文章数） | 否 |
|
||
| POST | `/api/comments` | 提交评论 | 否 |
|
||
| GET | `/api/me` | 当前用户 | 是 |
|
||
|
||
## 示例
|
||
|
||
### 站点信息
|
||
|
||
```bash
|
||
curl http://laralog.test/api/site
|
||
```
|
||
|
||
```json
|
||
{"name":"旧博客的名字","description":"老博客描述","icp":"京ICP备12345678号","url":"http://laralog.test","rss":"http://laralog.test/rss.xml","api_version":"1.0"}
|
||
```
|
||
|
||
### 文章列表
|
||
|
||
```bash
|
||
curl "http://laralog.test/api/posts?page=1&per_page=10&category=tech&tag=laravel&q=关键词"
|
||
```
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": 1, "title": "你好，世界", "slug": "post-1",
|
||
"excerpt": "第一篇博客文章", "category": "生活随笔",
|
||
"tags": ["随笔"], "views": 100, "comment_count": 2,
|
||
"published_at": "2020-09-13T12:26:40+00:00",
|
||
"url": "http://laralog.test/posts/post-1.shtml"
|
||
}
|
||
],
|
||
"meta": { "current_page": 1, "last_page": 1, "per_page": 10, "total": 1 }
|
||
}
|
||
```
|
||
|
||
### 文章详情
|
||
|
||
```bash
|
||
curl http://laralog.test/api/posts/post-1
|
||
```
|
||
|
||
返回 `content_html`（与前台一致：Markdown 渲染 / [attach] 短代码解析 / 付费内容过滤）。
|
||
|
||
### 提交评论
|
||
|
||
```bash
|
||
curl -X POST http://laralog.test/api/comments \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"post_id":1,"author_name":"访客","content":"写得很好","website":""}'
|
||
```
|
||
|
||
- `website` 为蜜罐字段，必须留空
|
||
- 评论审核开关（comment_audit）开启时返回 `pending`，关闭直接发布
|
||
|
||
### 小程序接入建议
|
||
|
||
- 启动时请求 `/api/site` + `/api/posts` 缓存首页
|
||
- 文章详情拉取 `content_html` 直接渲染（富文本/图片已含 S3 URL）
|
||
- 评论提交带 `post_id`；如需"我的评论/会员"能力，用 Bearer Token 调 `/api/me`（可扩展）
|