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 }