固定文章编码

docs/api.yaml

@@ -1944,17 +1944,39 @@ components:
           properties:
             keyword:
               type: string
+              description: 按文章标题或编码模糊查询
             group_id:
               type: integer
             status:
               type: integer
               enum: [0, 1]
 
+    GetArticleRequest:
+      type: object
+      description: `id` 与 `code` 必须且只能提供一个。按 `id` 查询用于兼容旧文章链接，按 `code` 查询用于固定引用链接。
+      properties:
+        id:
+          type: integer
+        code:
+          type: string
+          minLength: 1
+          maxLength: 64
+          pattern: "^[a-z0-9][a-z0-9_-]{0,63}$"
+      oneOf:
+        - required: [id]
+        - required: [code]
+
     CreateArticleRequest:
       type: object
       properties:
         group_id:
           type: integer
+        code:
+          type: string
+          description: 可选的文章编码，用于固定引用链接；在未删除文章中唯一
+          minLength: 1
+          maxLength: 64
+          pattern: "^[a-z0-9][a-z0-9_-]{0,63}$"
         title:
           type: string
         content:
@@ -1975,6 +1997,12 @@ components:
           type: integer
         group_id:
           type: integer
+        code:
+          type: string
+          description: 可修改的文章编码；在未删除文章中唯一
+          minLength: 1
+          maxLength: 64
+          pattern: "^[a-z0-9][a-z0-9_-]{0,63}$"
         title:
           type: string
         content:
@@ -2057,6 +2085,9 @@ components:
       properties:
         id:
           type: integer
+        code:
+          type: string
+          description: 旧文章可能没有编码
         title:
           type: string
         updated_at:
@@ -2105,6 +2136,9 @@ components:
       properties:
         id:
           type: integer
+        code:
+          type: string
+          description: 旧文章可能没有编码
         title:
           type: string
         content:
@@ -2468,6 +2502,9 @@ components:
           properties:
             group_id:
               type: integer
+            code:
+              type: string
+              description: 旧文章可能没有编码
             title:
               type: string
             sort:
@@ -3834,7 +3871,7 @@ paths:
     post:
       tags: [client/article]
       summary: 获取文档详情
-      description: 仅官方客户端可调用。
+      description: 仅官方客户端可调用。支持按文章 ID 或编码查询，二者必须且只能提供一个。
       security:
         - basicAuth: []
         - bearerAuth: []
@@ -3843,7 +3880,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/IdRequest"
+              $ref: "#/components/schemas/GetArticleRequest"
       responses:
         "200":
           description: 文档详情