{ "swagger": "2.0", "info": { "description": "小说阅读APP 后端接口：公共内容浏览、用户行为、后台管理、Agent(MCP) 接入。", "title": "小说媒体APP 服务端 API", "contact": {}, "version": "1.0" }, "basePath": "/", "paths": { "/api/admin/v1/chapters/{id}": { "put": { "security": [ { "AdminAuth": [] } ], "description": "可修改序号、标题、正文、状态（隐藏/展示）、付费标识", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-章节管理" ], "summary": "编辑章节", "parameters": [ { "type": "integer", "description": "章节 ID", "name": "id", "in": "path", "required": true }, { "description": "章节信息（全量覆盖）", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.chapterReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } }, "delete": { "security": [ { "AdminAuth": [] } ], "produces": [ "application/json" ], "tags": [ "后台-章节管理" ], "summary": "删除章节", "parameters": [ { "type": "integer", "description": "章节 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/login": { "post": { "description": "后台管理员账号密码登录，签发 admin JWT", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "系统鉴权" ], "summary": "管理员登录", "parameters": [ { "description": "登录凭证", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.loginReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.tokenResp" } } } ] } }, "401": { "description": "账号或密码错误", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/novels": { "get": { "security": [ { "AdminAuth": [] } ], "description": "含下架小说；支持关键词筛选", "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "小说列表", "parameters": [ { "type": "string", "description": "书名/作者关键词", "name": "keyword", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_NovelAdminDTO" } } } ] } } } }, "post": { "security": [ { "AdminAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "新增小说", "parameters": [ { "description": "小说信息（可携带初始标签）", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.novelReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "integer" } } } } ] } } } } }, "/api/admin/v1/novels/{id}": { "put": { "security": [ { "AdminAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "编辑小说", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "description": "小说信息（全量覆盖）", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.novelReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } }, "delete": { "security": [ { "AdminAuth": [] } ], "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "删除小说", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/novels/{id}/chapters": { "post": { "security": [ { "AdminAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-章节管理" ], "summary": "新增章节", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "description": "章节信息", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.chapterReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/novels/{id}/status": { "put": { "security": [ { "AdminAuth": [] } ], "description": "0=下架隐藏 1=连载中 2=已完结", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "修改小说状态", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "description": "目标状态", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.novelStatusReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/novels/{id}/tags": { "put": { "security": [ { "AdminAuth": [] } ], "description": "小说多标签绑定（跨分组、幂等）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "绑定标签", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "description": "标签 ID 列表", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.bindTagsReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/novels/{id}/tags/{tagId}": { "delete": { "security": [ { "AdminAuth": [] } ], "produces": [ "application/json" ], "tags": [ "后台-小说管理" ], "summary": "解绑标签", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "标签 ID", "name": "tagId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/tag-groups": { "get": { "security": [ { "AdminAuth": [] } ], "description": "后台全量分组（含禁用），含下属全部标签", "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "标签分组列表", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/service.TagGroupDTO" } } } } ] } } } }, "post": { "security": [ { "AdminAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "新增标签分组", "parameters": [ { "description": "分组信息", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.groupReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } }, "409": { "description": "分组名称已存在", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/tag-groups/{id}": { "put": { "security": [ { "AdminAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "编辑标签分组", "parameters": [ { "type": "integer", "description": "分组 ID", "name": "id", "in": "path", "required": true }, { "description": "变更字段（可只传部分）", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.groupUpdateReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } }, "delete": { "security": [ { "AdminAuth": [] } ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "删除标签分组", "parameters": [ { "type": "integer", "description": "分组 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/tags": { "get": { "security": [ { "AdminAuth": [] } ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "分组标签列表", "parameters": [ { "type": "integer", "description": "分组 ID", "name": "group_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/service.TagDTO" } } } } ] } } } }, "post": { "security": [ { "AdminAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "新增标签", "parameters": [ { "description": "标签信息", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.tagReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/admin/v1/tags/{id}": { "put": { "security": [ { "AdminAuth": [] } ], "description": "支持修改名称、排序、状态、归属分组", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "编辑标签", "parameters": [ { "type": "integer", "description": "标签 ID", "name": "id", "in": "path", "required": true }, { "description": "变更字段", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.tagUpdateReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } }, "delete": { "security": [ { "AdminAuth": [] } ], "produces": [ "application/json" ], "tags": [ "后台-标签管理" ], "summary": "删除标签", "parameters": [ { "type": "integer", "description": "标签 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/authors/by-name": { "get": { "security": [ { "UserAuth": [] } ], "produces": [ "application/json" ], "tags": [ "作者" ], "summary": "按作者名查询作者", "parameters": [ { "type": "string", "description": "作者名", "name": "name", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.AuthorDTO" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/authors/{id}": { "get": { "security": [ { "UserAuth": [] } ], "produces": [ "application/json" ], "tags": [ "作者" ], "summary": "作者主页详情", "parameters": [ { "type": "integer", "description": "作者 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.AuthorDTO" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/authors/{id}/follow": { "post": { "security": [ { "UserAuth": [] } ], "tags": [ "作者" ], "summary": "关注作者", "parameters": [ { "type": "integer", "description": "作者 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } }, "delete": { "security": [ { "UserAuth": [] } ], "tags": [ "作者" ], "summary": "取消关注", "parameters": [ { "type": "integer", "description": "作者 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/authors/{id}/follow/status": { "get": { "security": [ { "UserAuth": [] } ], "tags": [ "作者" ], "summary": "查询是否已关注", "parameters": [ { "type": "integer", "description": "作者 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } } }, "/api/v1/authors/{id}/novels": { "get": { "produces": [ "application/json" ], "tags": [ "作者" ], "summary": "作者作品列表", "parameters": [ { "type": "integer", "description": "作者 ID", "name": "id", "in": "path" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_NovelSummaryDTO" } } } ] } } } } }, "/api/v1/categories": { "get": { "description": "前台分类页：按权重排序的启用分组及其启用标签", "produces": [ "application/json" ], "tags": [ "内容浏览" ], "summary": "标签分组列表", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/service.TagGroupDTO" } } } } ] } } } } }, "/api/v1/novels": { "get": { "description": "关键词 + 多标签（AND 语义）筛选，按权重排序分页返回", "produces": [ "application/json" ], "tags": [ "内容浏览" ], "summary": "小说检索", "parameters": [ { "type": "string", "description": "书名/作者关键词", "name": "keyword", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "标签 ID（多选）", "name": "tag_ids", "in": "query" }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量，默认 20，最大 50", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_NovelSummaryDTO" } } } ] } } } } }, "/api/v1/novels/{id}": { "get": { "description": "封面、简介、连载状态、绑定标签（下架小说不可见）", "produces": [ "application/json" ], "tags": [ "内容浏览" ], "summary": "小说详情", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.NovelDetailDTO" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/novels/{id}/chapters": { "get": { "description": "按序号正序返回展示中的章节（隐藏章节不可见），含付费标识", "produces": [ "application/json" ], "tags": [ "内容浏览" ], "summary": "章节目录", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "每页数量，默认 50，最大 100", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_ChapterItemDTO" } } } ] } } } } }, "/api/v1/novels/{id}/chapters/{cid}": { "get": { "description": "返回章节正文；付费章节未登录时返回 locked=true（商业化预埋）", "produces": [ "application/json" ], "tags": [ "内容浏览" ], "summary": "章节阅读", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "章节 ID", "name": "cid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ChapterContentDTO" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/recommend": { "get": { "description": "热门（权重排序）或新书（上架时间排序）推荐", "produces": [ "application/json" ], "tags": [ "内容浏览" ], "summary": "推荐列表", "parameters": [ { "type": "string", "description": "hot（默认）/ new", "name": "type", "in": "query" }, { "type": "integer", "default": 10, "description": "数量，默认 10，最大 50", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/service.NovelSummaryDTO" } } } } ] } } } } }, "/api/v1/user/favorites": { "get": { "security": [ { "UserAuth": [] } ], "produces": [ "application/json" ], "tags": [ "用户行为" ], "summary": "我的收藏列表", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_NovelSummaryDTO" } } } ] } } } }, "post": { "security": [ { "UserAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "用户行为" ], "summary": "收藏小说", "parameters": [ { "description": "小说 ID", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.collectReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/user/favorites/{novelId}": { "delete": { "security": [ { "UserAuth": [] } ], "produces": [ "application/json" ], "tags": [ "用户行为" ], "summary": "取消收藏", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "novelId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/user/favorites/{novelId}/status": { "get": { "security": [ { "UserAuth": [] } ], "tags": [ "用户行为" ], "summary": "查询是否已收藏", "parameters": [ { "type": "integer", "description": "小说 ID", "name": "novelId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } } }, "/api/v1/user/follows": { "get": { "security": [ { "UserAuth": [] } ], "produces": [ "application/json" ], "tags": [ "作者" ], "summary": "我的关注列表", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_AuthorDTO" } } } ] } } } } }, "/api/v1/user/history": { "get": { "security": [ { "UserAuth": [] } ], "description": "按最近阅读倒序", "produces": [ "application/json" ], "tags": [ "用户行为" ], "summary": "阅读历史列表", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.PageDTO-service_NovelSummaryDTO" } } } ] } } } } }, "/api/v1/user/login": { "post": { "description": "移动端用户登录，签发 user JWT", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "用户鉴权" ], "summary": "用户登录", "parameters": [ { "description": "登录凭证", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.userLoginReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.userIDResp" } } } ] } }, "401": { "description": "账号或密码错误", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/user/progress": { "post": { "security": [ { "UserAuth": [] } ], "description": "记录最后阅读位置并刷新阅读历史（服务端时间戳覆盖策略）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "用户行为" ], "summary": "上报阅读进度", "parameters": [ { "description": "进度信息", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.progressReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.Response" } } } } }, "/api/v1/user/register": { "post": { "description": "移动端用户手机号注册", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "用户鉴权" ], "summary": "用户注册", "parameters": [ { "description": "注册信息", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.registerReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/handler.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.userIDResp" } } } ] } }, "409": { "description": "手机号已注册", "schema": { "$ref": "#/definitions/handler.Response" } } } } } }, "definitions": { "handler.Response": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": {}, "msg": { "type": "string", "example": "ok" } } }, "handler.bindTagsReq": { "type": "object", "required": [ "tag_ids" ], "properties": { "tag_ids": { "type": "array", "items": { "type": "integer" } } } }, "handler.chapterReq": { "type": "object", "required": [ "seq", "title" ], "properties": { "content": { "type": "string" }, "is_paid": { "type": "boolean" }, "seq": { "type": "integer", "example": 1 }, "status": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "第一章 初入江湖" } } }, "handler.collectReq": { "type": "object", "required": [ "novel_id" ], "properties": { "novel_id": { "type": "integer" } } }, "handler.groupReq": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "小说题材" }, "sort": { "type": "integer", "example": 1 } } }, "handler.groupUpdateReq": { "type": "object", "properties": { "name": { "type": "string" }, "sort": { "type": "integer" }, "status": { "type": "integer", "example": 1 } } }, "handler.loginReq": { "type": "object", "required": [ "password", "username" ], "properties": { "password": { "type": "string", "example": "123456" }, "username": { "type": "string", "example": "admin" } } }, "handler.novelReq": { "type": "object", "required": [ "title" ], "properties": { "author": { "type": "string", "example": "笔耕不辍" }, "cover": { "type": "string", "example": "https://cdn.example.com/cover.jpg" }, "intro": { "type": "string" }, "is_paid": { "type": "boolean" }, "show_ad": { "type": "boolean" }, "sort_weight": { "type": "integer" }, "status": { "type": "integer", "example": 1 }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "title": { "type": "string", "example": "都市之巅" } } }, "handler.novelStatusReq": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "integer", "example": 2 } } }, "handler.progressReq": { "type": "object", "required": [ "chapter_id", "novel_id" ], "properties": { "chapter_id": { "type": "integer" }, "novel_id": { "type": "integer" }, "progress": { "type": "integer", "example": 35 } } }, "handler.registerReq": { "type": "object", "required": [ "password", "phone" ], "properties": { "nickname": { "type": "string", "example": "书虫小明" }, "password": { "type": "string", "minLength": 6, "example": "123456" }, "phone": { "type": "string", "example": "13800138000" } } }, "handler.tagReq": { "type": "object", "required": [ "group_id", "name" ], "properties": { "group_id": { "type": "integer" }, "name": { "type": "string", "example": "玄幻" }, "sort": { "type": "integer" } } }, "handler.tagUpdateReq": { "type": "object", "properties": { "group_id": { "type": "integer" }, "name": { "type": "string" }, "sort": { "type": "integer" }, "status": { "type": "integer" } } }, "handler.tokenResp": { "type": "object", "properties": { "token": { "type": "string" } } }, "handler.userIDResp": { "type": "object", "properties": { "token": { "type": "string" }, "user_id": { "type": "integer" } } }, "handler.userLoginReq": { "type": "object", "required": [ "password", "phone" ], "properties": { "password": { "type": "string", "example": "123456" }, "phone": { "type": "string", "example": "13800138000" } } }, "service.AuthorDTO": { "type": "object", "properties": { "avatar": { "description": "空时客户端渲染首字圆形占位", "type": "string" }, "bio": { "type": "string" }, "follower_count": { "type": "integer" }, "id": { "type": "integer" }, "is_following": { "description": "仅登录用户有意义，游客恒 false", "type": "boolean" }, "name": { "type": "string" }, "novel_count": { "type": "integer" } } }, "service.ChapterContentDTO": { "type": "object", "properties": { "content": { "type": "string" }, "id": { "type": "integer" }, "is_paid": { "type": "boolean" }, "locked": { "description": "付费且无权限：content 为空、locked=true（商业化预埋校验位）", "type": "boolean" }, "seq": { "type": "integer" }, "title": { "type": "string" } } }, "service.ChapterItemDTO": { "type": "object", "properties": { "id": { "type": "integer" }, "is_paid": { "type": "boolean" }, "seq": { "type": "integer" }, "title": { "type": "string" } } }, "service.NovelAdminDTO": { "type": "object", "properties": { "author": { "type": "string" }, "cover": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "is_paid": { "type": "boolean" }, "show_ad": { "type": "boolean" }, "sort_weight": { "type": "integer" }, "status": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "title": { "type": "string" }, "total_chapters": { "type": "integer" } } }, "service.NovelDetailDTO": { "type": "object", "properties": { "author": { "type": "string" }, "cover": { "description": "封面相对路径或完整 URL", "type": "string" }, "id": { "type": "integer" }, "intro": { "type": "string" }, "intro_brief": { "type": "string" }, "is_paid": { "type": "boolean" }, "read_count": { "description": "人气值（阅读次数）", "type": "integer" }, "status": { "description": "1=连载中 2=已完结", "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tag_names": { "description": "标签名（客户端卡片直显）", "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/service.TagDTO" } }, "title": { "type": "string" }, "total_chapters": { "type": "integer" } } }, "service.NovelSummaryDTO": { "type": "object", "properties": { "author": { "type": "string" }, "cover": { "description": "封面相对路径或完整 URL", "type": "string" }, "id": { "type": "integer" }, "intro_brief": { "type": "string" }, "is_paid": { "type": "boolean" }, "read_count": { "description": "人气值（阅读次数）", "type": "integer" }, "status": { "description": "1=连载中 2=已完结", "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tag_names": { "description": "标签名（客户端卡片直显）", "type": "array", "items": { "type": "string" } }, "title": { "type": "string" } } }, "service.PageDTO-service_AuthorDTO": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/definitions/service.AuthorDTO" } }, "total": { "type": "integer" } } }, "service.PageDTO-service_ChapterItemDTO": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/definitions/service.ChapterItemDTO" } }, "total": { "type": "integer" } } }, "service.PageDTO-service_NovelAdminDTO": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/definitions/service.NovelAdminDTO" } }, "total": { "type": "integer" } } }, "service.PageDTO-service_NovelSummaryDTO": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/definitions/service.NovelSummaryDTO" } }, "total": { "type": "integer" } } }, "service.TagDTO": { "type": "object", "properties": { "group_id": { "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "service.TagGroupDTO": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "sort": { "type": "integer" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/service.TagDTO" } } } } }, "securityDefinitions": { "AdminAuth": { "description": "后台管理员 JWT，格式：Bearer {token}", "type": "apiKey", "name": "Authorization", "in": "header" }, "AgentKey": { "description": "Agent 应用 API Key，格式：Bearer ak_{key}（MCP 通道调试接口）", "type": "apiKey", "name": "Authorization", "in": "header" }, "UserAuth": { "description": "移动端用户 JWT，格式：Bearer {token}", "type": "apiKey", "name": "Authorization", "in": "header" } } }