mint/openapi/public/assets/protocol/resources/auto/v3-discussions-discussion.yaml

# 由 openapi/scripts/generate.php 生成，请勿手改；补充写到 overrides/v3-discussions-discussion.yaml
get:
  summary: 获取单条话题或回复
  tags:
    - discussions
  operationId: get_api_v3_discussions_discussion_
  description: |-
    删除了但还有回复的话题返回墓碑；删除了的回复、删除了且没有回复的话题返回 404。
    当前用户看不见的话题同样 404。

    实现：`V3\DiscussionController@show`
  security:
    - {  }
    -
      bearerAuth: []
  parameters:
    -
      name: discussion
      in: path
      required: true
      schema:
        type: string
      description: '话题或回复的 uuid'
  responses:
    200:
      description: 成功
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    type: string
                  target_type:
                    type: string
                  target_id:
                    type: string
                  parent_id:
                    type: string
                    nullable: true
                  type:
                    type: string
                  severity:
                    type: string
                    nullable: true
                  status:
                    type: string
                  title:
                    type: string
                    nullable: true
                  content:
                    type: string
                    nullable: true
                  content_type:
                    type: string
                  html:
                    type: string
                    description: 仅在部分查询口径下返回。
                  summary:
                    type: string
                    description: 仅在部分查询口径下返回。
                  tpl_id:
                    type: string
                    nullable: true
                  pos_start:
                    type: integer
                    nullable: true
                  pos_end:
                    type: integer
                    nullable: true
                  quote_exact:
                    type: string
                    nullable: true
                  quote_prefix:
                    type: string
                    nullable: true
                  quote_suffix:
                    type: string
                    nullable: true
                  reply_count:
                    type: integer
                    description: 仅在部分查询口径下返回。
                  sentence:
                    type: object
                    properties:
                      book: { type: integer }
                      paragraph: { type: integer }
                      word_start: { type: integer }
                      word_end: { type: integer }
                    description: 仅在部分查询口径下返回。
                  editor:
                    type: object
                    properties:
                      id: { type: string }
                      nickName: { type: string }
                      userName: { type: string }
                      realName: { type: string }
                      sn: { type: integer }
                      avatar: { type: string }
                      roles: { type: array, items: { type: string } }
                    nullable: true
                  co_editor:
                    type: object
                    properties:
                      id: { type: string }
                      nickName: { type: string }
                      userName: { type: string }
                      realName: { type: string }
                      sn: { type: integer }
                      avatar: { type: string }
                      roles: { type: array, items: { type: string } }
                    nullable: true
                  abilities:
                    type: object
                    properties:
                      update: { type: boolean }
                      delete: { type: boolean }
                      close: { type: boolean }
                      reply: { type: boolean }
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  deleted_at:
                    type: string
                    nullable: true
    422:
      $ref: '../../main.yaml#/components/responses/ProblemValidation'
delete:
  summary: 删除话题或回复（软删除）
  tags:
    - discussions
  operationId: delete_api_v3_discussions_discussion_
  description: |-
    作者本人或挂靠对象的管理者（句子 / 逐词所在 channel、文章的编辑者）能删；
    v2 只允许作者。删话题不动回复：有回复的话题以墓碑形式留在列表里。
    返回删除后的资源（200），不是 204——软删的资源并没有消失。

    实现：`V3\DiscussionController@destroy`
  security:
    -
      bearerAuth: []
  parameters:
    -
      name: discussion
      in: path
      required: true
      schema:
        type: string
      description: '话题或回复的 uuid'
  responses:
    200:
      description: 成功
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    type: string
                  target_type:
                    type: string
                  target_id:
                    type: string
                  parent_id:
                    type: string
                    nullable: true
                  type:
                    type: string
                  severity:
                    type: string
                    nullable: true
                  status:
                    type: string
                  title:
                    type: string
                    nullable: true
                  content:
                    type: string
                    nullable: true
                  content_type:
                    type: string
                  html:
                    type: string
                    description: 仅在部分查询口径下返回。
                  summary:
                    type: string
                    description: 仅在部分查询口径下返回。
                  tpl_id:
                    type: string
                    nullable: true
                  pos_start:
                    type: integer
                    nullable: true
                  pos_end:
                    type: integer
                    nullable: true
                  quote_exact:
                    type: string
                    nullable: true
                  quote_prefix:
                    type: string
                    nullable: true
                  quote_suffix:
                    type: string
                    nullable: true
                  reply_count:
                    type: integer
                    description: 仅在部分查询口径下返回。
                  sentence:
                    type: object
                    properties:
                      book: { type: integer }
                      paragraph: { type: integer }
                      word_start: { type: integer }
                      word_end: { type: integer }
                    description: 仅在部分查询口径下返回。
                  editor:
                    type: object
                    properties:
                      id: { type: string }
                      nickName: { type: string }
                      userName: { type: string }
                      realName: { type: string }
                      sn: { type: integer }
                      avatar: { type: string }
                      roles: { type: array, items: { type: string } }
                    nullable: true
                  co_editor:
                    type: object
                    properties:
                      id: { type: string }
                      nickName: { type: string }
                      userName: { type: string }
                      realName: { type: string }
                      sn: { type: integer }
                      avatar: { type: string }
                      roles: { type: array, items: { type: string } }
                    nullable: true
                  abilities:
                    type: object
                    properties:
                      update: { type: boolean }
                      delete: { type: boolean }
                      close: { type: boolean }
                      reply: { type: boolean }
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  deleted_at:
                    type: string
                    nullable: true
    401:
      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
    403:
      description: 既不是作者，也不是挂靠对象的管理者
      content:
        application/problem+json:
          schema:
            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
    422:
      $ref: '../../main.yaml#/components/responses/ProblemValidation'
patch:
  summary: 修改话题或回复（局部更新）
  tags:
    - discussions
  operationId: patch_api_v3_discussions_discussion_
  description: |-
    只改传了的字段。title / status / type / severity 只对话题有效，回复传了 422。
    作者或对象的管理者（句子、逐词所在 channel 的编辑者，文章的编辑者）可改；
    改 type 时回复跟着改，新类型不收原来的 severity 时 severity 清空（锚点保留，改回可带锚点的类型时恢复）；
    改成 glossary 须挂在句子上、且是该句的管理者。
    批注：没有 status，type 只能在 note / commentary 之间改（不能与评论线程互转），
    正文不能清空，可改锚点。
    改了内容（标题、正文、锚点）时 co_editor 跟着这次写入走：人亲自改则清空，AI 代改则换成该模型；
    只改 status / type / severity 不动 co_editor。

    实现：`V3\DiscussionController@update`
  security:
    -
      bearerAuth: []
  parameters:
    -
      name: discussion
      in: path
      required: true
      schema:
        type: string
      description: '话题或回复的 uuid'
  requestBody:
    required: false
    content:
      application/json:
        schema:
          type: object
          properties:
            title:
              type: string
              description: 标题（只限话题）
            content:
              type: string
              description: 正文（markdown）
            status:
              type: string
              description: 状态（只限话题）
              enum:
                - active
                - close
            type:
              type: string
              description: 类型（只限话题；评论线程与批注不能互转）
              enum:
                - discussion
                - qa
                - help
                - issue
                - glossary
                - note
                - commentary
            severity:
              type: string
              description: '严重程度（只限话题），null 表示清空'
              enum:
                - error
                - warning
                - suggestion
                - urgent
                - normal
            pos_start:
              type: integer
              description: '锚点起始偏移（只限 note / commentary / issue / glossary）'
            pos_end:
              type: integer
              description: '锚点结束偏移（只限 note / commentary / issue / glossary）'
            quote_exact:
              type: string
              description: '锚定的原文片段（只限 note / commentary / issue / glossary）'
            quote_prefix:
              type: string
              description: '锚定片段前的上下文（只限 note / commentary / issue / glossary）'
            quote_suffix:
              type: string
              description: '锚定片段后的上下文（只限 note / commentary / issue / glossary）'
  responses:
    200:
      description: 成功
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    type: string
                  target_type:
                    type: string
                  target_id:
                    type: string
                  parent_id:
                    type: string
                    nullable: true
                  type:
                    type: string
                  severity:
                    type: string
                    nullable: true
                  status:
                    type: string
                  title:
                    type: string
                    nullable: true
                  content:
                    type: string
                    nullable: true
                  content_type:
                    type: string
                  html:
                    type: string
                    description: 仅在部分查询口径下返回。
                  summary:
                    type: string
                    description: 仅在部分查询口径下返回。
                  tpl_id:
                    type: string
                    nullable: true
                  pos_start:
                    type: integer
                    nullable: true
                  pos_end:
                    type: integer
                    nullable: true
                  quote_exact:
                    type: string
                    nullable: true
                  quote_prefix:
                    type: string
                    nullable: true
                  quote_suffix:
                    type: string
                    nullable: true
                  reply_count:
                    type: integer
                    description: 仅在部分查询口径下返回。
                  sentence:
                    type: object
                    properties:
                      book: { type: integer }
                      paragraph: { type: integer }
                      word_start: { type: integer }
                      word_end: { type: integer }
                    description: 仅在部分查询口径下返回。
                  editor:
                    type: object
                    properties:
                      id: { type: string }
                      nickName: { type: string }
                      userName: { type: string }
                      realName: { type: string }
                      sn: { type: integer }
                      avatar: { type: string }
                      roles: { type: array, items: { type: string } }
                    nullable: true
                  co_editor:
                    type: object
                    properties:
                      id: { type: string }
                      nickName: { type: string }
                      userName: { type: string }
                      realName: { type: string }
                      sn: { type: integer }
                      avatar: { type: string }
                      roles: { type: array, items: { type: string } }
                    nullable: true
                  abilities:
                    type: object
                    properties:
                      update: { type: boolean }
                      delete: { type: boolean }
                      close: { type: boolean }
                      reply: { type: boolean }
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  deleted_at:
                    type: string
                    nullable: true
    401:
      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
    403:
      description: 没有修改权限
      content:
        application/problem+json:
          schema:
            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
    422:
      $ref: '../../main.yaml#/components/responses/ProblemValidation'