openapi: 3.0.0
info:
  description: |
    Welcome to the HumHub comment module API reference.
  version: 1.0.0
  title: HumHub - Content API
  contact:
    email: info@humhub.com
  license:
    name: AGPLv2
    url: https://www.humhub.org/en/licences
paths:
  /comment/find-by-object:
    get:
      summary: Find comments by object
      parameters:
        - name: objectModel
          in: query
          description: The object model class name
          required: true
          schema:
            type: string
        - name: objectId
          in: query
          description: The primary key of the object
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  pages:
                    $ref: common.yaml#/components/schemas/pagesProperty
                  links:
                    $ref: common.yaml#/components/schemas/linksProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Comment"
        "403":
          description: You cannot view this content!
        "404":
          description: Content not found!
  "/comment/content/{id}":
    get:
      summary: Find comments by content
      parameters:
        - name: id
          in: path
          description: The primary key of the content
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  pages:
                    $ref: common.yaml#/components/schemas/pagesProperty
                  links:
                    $ref: common.yaml#/components/schemas/linksProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Comment"
        "403":
          description: You cannot view this content!
        "404":
          description: Content not found!
  /comment:
    post:
      summary: Create a comment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - objectModel
                - objectId
                - Comment
              properties:
                objectModel:
                  type: string
                  example: humhub\modules\post\models\Post
                objectId:
                  type: integer
                  format: int64
                  example: 123
                Comment:
                  $ref: "#/components/schemas/Comment"
        description: The comment data
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "400":
          description: Validation failed
        "403":
          description: You cannot comment the content!
  "/comment/{id}":
    get:
      summary: Get comment by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of the comment
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "400":
          description: Invalid comment id supplied
        "404":
          description: Comment not found
    put:
      summary: Update a comment by id
      parameters:
        - name: id
          in: path
          description: Id of the updated comment
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - Comment
              properties:
                Comment:
                  $ref: "#/components/schemas/Comment"
        description: The comment data
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "400":
          description: Validation failed
        "403":
          description: You cannot update this comment!
        "404":
          description: Comment not found!
    delete:
      summary: Deletes a comment by id
      parameters:
        - name: id
          in: path
          description: The id of comment
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: successful operation
        "404":
          description: Comment not found
servers:
  - url: /api/v1
components:
  securitySchemes:
    _ref: common.yaml#/securityDefinitions
  schemas:
    CommentsSummary:
      type: object
      properties:
        total:
          type: integer
          format: int64
          readOnly: true
          example: 55
        latestComments:
          type: array
          items:
            $ref: "#/components/schemas/Comment"
    Comment:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          example: 14
        message:
          type: string
          example: Calvin Klein – Between love and madness lies obsession.
        objectModel:
          type: string
          readOnly: true
          example: humhub\modules\post\models\Post
        objectId:
          type: integer
          format: int64
          readOnly: true
          example: 123
        createdBy:
          readOnly: true
          allOf:
            - $ref: user.yaml#/components/schemas/UserShort
        createdAt:
          type: string
          readOnly: true
          example: 2018-08-09 14:22:03
        commentsCount:
          type: integer
          readOnly: true
          example: 5
        comments:
          type: array
          readOnly: true
          items:
            $ref: "#/components/schemas/Comment"
