# 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`（可扩展）