{
  "openapi": "3.1.0",
  "info": {
    "title": "Resonare 公开只读 API",
    "description": "WordPress REST API 的精选只读子集。本契约仅收录匿名可访问的内容查询端点；写入与管理端点不在公开范围。列表接口统一支持 X-WP-Total / X-WP-TotalPages 分页头。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://resonare.cn/wp-json",
      "description": "生产环境"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "API 发现索引",
        "description": "返回全部路由及其参数定义，Agent 首次接入时的推荐起点。",
        "operationId": "getIndex",
        "responses": {
          "200": {
            "description": "路由索引",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/wp/v2/posts": {
      "get": {
        "summary": "文章列表",
        "operationId": "listPosts",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Search" },
          { "$ref": "#/components/parameters/Context" },
          { "$ref": "#/components/parameters/Fields" },
          { "$ref": "#/components/parameters/Embed" },
          {
            "name": "categories",
            "in": "query",
            "required": false,
            "description": "按分类 ID 过滤，逗号分隔多个。常用：随笔 2、技术 3。",
            "schema": { "type": "string" },
            "example": "2,3"
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "按标签 ID 过滤，逗号分隔多个。",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "文章数组",
            "headers": {
              "X-WP-Total": { "$ref": "#/components/headers/XWPTotal" },
              "X-WP-TotalPages": { "$ref": "#/components/headers/XWPTotalPages" }
            },
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }
              }
            }
          }
        }
      }
    },
    "/wp/v2/posts/{id}": {
      "get": {
        "summary": "单篇文章",
        "operationId": "getPost",
        "parameters": [
          { "$ref": "#/components/parameters/Id" },
          { "$ref": "#/components/parameters/Context" },
          { "$ref": "#/components/parameters/Fields" }
        ],
        "responses": {
          "200": {
            "description": "文章详情",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Post" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/wp/v2/pages": {
      "get": {
        "summary": "独立页面列表",
        "description": "含「关于」「友链」「简历」等静态页。",
        "operationId": "listPages",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Search" },
          { "$ref": "#/components/parameters/Context" },
          { "$ref": "#/components/parameters/Fields" }
        ],
        "responses": {
          "200": {
            "description": "页面数组",
            "headers": {
              "X-WP-Total": { "$ref": "#/components/headers/XWPTotal" },
              "X-WP-TotalPages": { "$ref": "#/components/headers/XWPTotalPages" }
            },
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Page" } }
              }
            }
          }
        }
      }
    },
    "/wp/v2/pages/{id}": {
      "get": {
        "summary": "单个独立页面",
        "operationId": "getPage",
        "parameters": [
          { "$ref": "#/components/parameters/Id" },
          { "$ref": "#/components/parameters/Context" }
        ],
        "responses": {
          "200": {
            "description": "页面详情",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Page" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/wp/v2/media": {
      "get": {
        "summary": "媒体库列表",
        "operationId": "listMedia",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Search" },
          { "$ref": "#/components/parameters/MediaType" },
          { "$ref": "#/components/parameters/Embed" }
        ],
        "responses": {
          "200": {
            "description": "媒体项数组",
            "headers": {
              "X-WP-Total": { "$ref": "#/components/headers/XWPTotal" },
              "X-WP-TotalPages": { "$ref": "#/components/headers/XWPTotalPages" }
            },
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }
              }
            }
          }
        }
      }
    },
    "/wp/v2/media/{id}": {
      "get": {
        "summary": "单个媒体项",
        "operationId": "getMedia",
        "parameters": [
          { "$ref": "#/components/parameters/Id" },
          { "$ref": "#/components/parameters/Embed" }
        ],
        "responses": {
          "200": {
            "description": "媒体详情（含各尺寸 source_url）",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/MediaItem" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/wp/v2/comments": {
      "get": {
        "summary": "公开评论列表",
        "operationId": "listComments",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Search" },
          {
            "name": "post",
            "in": "query",
            "required": false,
            "description": "限定某篇文章下的评论。",
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "评论数组",
            "headers": {
              "X-WP-Total": { "$ref": "#/components/headers/XWPTotal" },
              "X-WP-TotalPages": { "$ref": "#/components/headers/XWPTotalPages" }
            },
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }
              }
            }
          }
        }
      }
    },
    "/wp/v2/categories": {
      "get": {
        "summary": "分类目录",
        "operationId": "listCategories",
        "parameters": [
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Search" },
          { "$ref": "#/components/parameters/HideEmpty" }
        ],
        "responses": {
          "200": {
            "description": "分类数组",
            "headers": {
              "X-WP-Total": { "$ref": "#/components/headers/XWPTotal" },
              "X-WP-TotalPages": { "$ref": "#/components/headers/XWPTotalPages" }
            },
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } }
              }
            }
          }
        }
      }
    },
    "/wp/v2/categories/{id}": {
      "get": {
        "summary": "单个分类",
        "operationId": "getCategory",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": {
          "200": {
            "description": "分类详情",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Term" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/wp/v2/tags": {
      "get": {
        "summary": "标签目录",
        "operationId": "listTags",
        "parameters": [
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Search" },
          { "$ref": "#/components/parameters/HideEmpty" }
        ],
        "responses": {
          "200": {
            "description": "标签数组",
            "headers": {
              "X-WP-Total": { "$ref": "#/components/headers/XWPTotal" },
              "X-WP-TotalPages": { "$ref": "#/components/headers/XWPTotalPages" }
            },
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } }
              }
            }
          }
        }
      }
    },
    "/wp/v2/tags/{id}": {
      "get": {
        "summary": "单个标签",
        "operationId": "getTag",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": {
          "200": {
            "description": "标签详情",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Term" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "资源数字 ID。",
        "schema": { "type": "integer" }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "当前页码，从 1 开始。",
        "schema": { "type": "integer", "default": 1, "minimum": 1 }
      },
      "PerPage": {
        "name": "per_page",
        "in": "query",
        "required": false,
        "description": "每页条数，上限 100。",
        "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100 }
      },
      "Search": {
        "name": "search",
        "in": "query",
        "required": false,
        "description": "全文关键词。",
        "schema": { "type": "string" }
      },
      "Context": {
        "name": "context",
        "in": "query",
        "required": false,
        "description": "视图范围；匿名请求固定为 view。",
        "schema": { "type": "string", "enum": ["view"], "default": "view" }
      },
      "Fields": {
        "name": "_fields",
        "in": "query",
        "required": false,
        "description": "裁剪响应字段以减小载荷，逗号分隔。",
        "schema": { "type": "string" },
        "example": "id,title,link,date,excerpt"
      },
      "Embed": {
        "name": "_embed",
        "in": "query",
        "required": false,
        "description": "内嵌关联资源（作者、特色图、分类）到 _links._embedded。",
        "schema": { "type": "boolean", "default": false }
      },
      "MediaType": {
        "name": "media_type",
        "in": "query",
        "required": false,
        "description": "按 MIME 大类过滤。",
        "schema": { "type": "string", "enum": ["image", "video", "text", "application", "audio", "file"] }
      },
      "HideEmpty": {
        "name": "hide_empty",
        "in": "query",
        "required": false,
        "description": "是否隐藏无内容的分类/标签。",
        "schema": { "type": "boolean", "default": false }
      }
    },
    "headers": {
      "XWPTotal": {
        "description": "过滤后的资源总数，用于精确翻页。",
        "schema": { "type": "integer" }
      },
      "XWPTotalPages": {
        "description": "总页数。",
        "schema": { "type": "integer" }
      }
    },
    "schemas": {
      "RenderedText": {
        "type": "object",
        "properties": {
          "rendered": { "type": "string", "description": "HTML 渲染结果。" }
        }
      },
      "TitleExcerpt": {
        "type": "object",
        "properties": {
          "raw": { "type": "string" },
          "rendered": { "type": "string" }
        }
      },
      "Post": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "date": { "type": "string", "format": "date-time" },
          "modified": { "type": "string", "format": "date-time" },
          "slug": { "type": "string" },
          "status": { "type": "string", "enum": ["publish"] },
          "link": { "type": "string", "format": "uri" },
          "title": { "$ref": "#/components/schemas/RenderedText" },
          "content": { "$ref": "#/components/schemas/TitleExcerpt" },
          "excerpt": { "$ref": "#/components/schemas/TitleExcerpt" },
          "author": { "type": "integer" },
          "featured_media": { "type": "integer" },
          "categories": { "type": "array", "items": { "type": "integer" } },
          "tags": { "type": "array", "items": { "type": "integer" } }
        }
      },
      "Page": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "date": { "type": "string", "format": "date-time" },
          "modified": { "type": "string", "format": "date-time" },
          "slug": { "type": "string" },
          "status": { "type": "string", "enum": ["publish"] },
          "link": { "type": "string", "format": "uri" },
          "title": { "$ref": "#/components/schemas/RenderedText" },
          "content": { "$ref": "#/components/schemas/TitleExcerpt" },
          "excerpt": { "$ref": "#/components/schemas/TitleExcerpt" },
          "parent": { "type": "integer" },
          "menu_order": { "type": "integer" }
        }
      },
      "MediaItem": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "date": { "type": "string", "format": "date-time" },
          "slug": { "type": "string" },
          "post": { "type": ["integer", "null"], "description": "所属文章 ID，未关联时为 null。" },
          "source_url": { "type": "string", "format": "uri" },
          "mime_type": { "type": "string" },
          "media_type": { "type": "string" },
          "alt_text": { "type": "string" },
          "caption": { "$ref": "#/components/schemas/RenderedText" },
          "media_details": { "type": "object", "description": "尺寸信息，含各类 media_details.sizes[n].source_url。" }
        }
      },
      "Comment": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "post": { "type": "integer" },
          "parent": { "type": "integer" },
          "author_name": { "type": "string" },
          "date": { "type": "string", "format": "date-time" },
          "content": { "$ref": "#/components/schemas/RenderedText" },
          "link": { "type": "string", "format": "uri" },
          "status": { "type": "string", "enum": ["approved"] }
        }
      },
      "Term": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "count": { "type": "integer" },
          "description": { "type": "string" },
          "link": { "type": "string", "format": "uri" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "taxonomy": { "type": "string", "enum": ["category", "post_tag"] }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源不存在",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": { "type": "string", "example": "rest_post_invalid_id" },
                "message": { "type": "string" },
                "data": { "type": "object", "properties": { "status": { "type": "integer", "example": 404 } } }
              }
            }
          }
        }
      }
    }
  }
}