laralog/docs/api.md

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 需要

认证（可选）

# 生成 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	当前用户	是

示例

站点信息

curl http://laralog.test/api/site

{"name":"旧博客的名字","description":"老博客描述","icp":"京ICP备12345678号","url":"http://laralog.test","rss":"http://laralog.test/rss.xml","api_version":"1.0"}

文章列表

curl "http://laralog.test/api/posts?page=1&per_page=10&category=tech&tag=laravel&q=关键词"

{
  "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 }
}

文章详情

curl http://laralog.test/api/posts/post-1

返回 content_html（与前台一致：Markdown 渲染 / [attach] 短代码解析 / 付费内容过滤）。

提交评论

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