tss-rocks/api/schemas/paths/posts.yaml

posts:
  get:
    tags:
      - posts
    summary: 获取文章列表
    operationId: listPosts
    parameters:
      - $ref: '../components/parameters.yaml#/Page'
      - $ref: '../components/parameters.yaml#/PerPage'
      - $ref: '../components/parameters.yaml#/Language'
      - $ref: '../components/parameters.yaml#/Sort'
      - $ref: '../components/parameters.yaml#/Status'
      - name: category
        in: query
        schema:
          type: string
        description: 按分类筛选
    responses:
      '200':
        description: 成功获取文章列表
        content:
          application/json:
            schema:
              allOf:
                - $ref: '../components/schemas.yaml#/Response'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '../components/schemas.yaml#/Post'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
  post:
    tags:
      - posts
    summary: 创建新文章
    operationId: createPost
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - slug
              - contents
            properties:
              slug:
                type: string
              status:
                type: string
                enum:
                  - draft
                  - published
                default: draft
              contents:
                type: array
                items:
                  $ref: '../components/schemas.yaml#/PostContent'
              category_ids:
                type: array
                items:
                  type: integer
    responses:
      '201':
        description: 文章创建成功
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/Post'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '422':
        $ref: '../components/responses.yaml#/ValidationError'

post_slug:
  parameters:
    - $ref: '../components/parameters.yaml#/Slug'
  get:
    tags:
      - posts
    summary: 获取文章详情
    operationId: getPost
    parameters:
      - $ref: '../components/parameters.yaml#/Language'
    responses:
      '200':
        description: 成功获取文章详情
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/Post'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
  put:
    tags:
      - posts
    summary: 更新文章
    operationId: updatePost
    parameters:
      - $ref: '../components/parameters.yaml#/Slug'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - draft
                  - published
              contents:
                type: array
                items:
                  $ref: '../components/schemas.yaml#/PostContent'
              category_ids:
                type: array
                items:
                  type: integer
    responses:
      '200':
        description: 文章更新成功
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/Post'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '422':
        $ref: '../components/responses.yaml#/ValidationError'
  delete:
    tags:
      - posts
    summary: 删除文章
    operationId: deletePost
    parameters:
      - $ref: '../components/parameters.yaml#/Slug'
    responses:
      '204':
        description: 文章删除成功
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'

post_contributors:
  parameters:
    - $ref: '../components/parameters.yaml#/Slug'
  get:
    tags:
      - posts
    summary: 获取文章贡献者列表
    operationId: getPostContributors
    responses:
      '200':
        description: 成功获取贡献者列表
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      contributor:
                        $ref: '../components/schemas.yaml#/Contributor'
                      role:
                        type: string
                      language_code:
                        type: string
                        enum:
                          - en
                          - zh-Hans
                          - zh-Hant
      '404':
        $ref: '../components/responses.yaml#/NotFound'