Merge pull request #14202 from hellcp-work/comments-doc

Document comment endpoints

src/api/public/apidocs-new/OBS-v2.10.50.yaml

@@ -8,6 +8,7 @@ tags:
   - name: Attribute Namespaces
   - name: Attributes
   - name: Build
+  - name: Comments
   - name: Configuration
   - name: Distributions
   - name: General Information
@@ -135,6 +136,15 @@ paths:
   /build/{project_name}/{repository_name}/{architecture_name}/{package_name}/{file_name}?view=fileinfo:
     $ref: 'paths/build_project_name_repository_name_architecture_name_package_name_file_name_view_fileinfo.yaml'
 
+  /comment/{comment_id}:
+    $ref: 'paths/comment_comment_id.yaml'
+  /comments/request/{id}:
+    $ref: 'paths/comments_request_id.yaml'
+  /comments/project/{project_name}:
+    $ref: 'paths/comments_project_project_name.yaml'
+  /comments/package/{project_name}/{package_name}:
+    $ref: 'paths/comments_package_project_name_package_name.yaml'
+
   /configuration:
     $ref: 'paths/configuration.yaml'
 

src/api/public/apidocs-new/components/schemas/comment.yaml

@@ -0,0 +1,16 @@
+type: object
+properties:
+  id:
+    type: integer
+    xml:
+      attribute: true
+  who:
+    type: string
+    xml:
+      attribute: true
+  when:
+    type: string
+    xml:
+      attribute: true
+# This schema is incomplete due to https://github.com/OAI/OpenAPI-Specification/issues/630,
+# comment element should have content

src/api/public/apidocs-new/components/schemas/comments.yaml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  comment:
+    type: array
+    items:
+      $ref: 'comment.yaml'
+  request:
+    type: integer
+    xml:
+      attribute: true
+  package:
+    type: string
+    xml:
+      attribute: true
+  project:
+    type: string
+    xml:
+      attribute: true
+xml:
+  name: comments

src/api/public/apidocs-new/paths/comment_comment_id.yaml

@@ -0,0 +1,38 @@
+delete:
+  summary: Delete a comment
+  description: Delete a given comment based on its id.
+  security:
+    - basic_authentication: []
+  parameters:
+    - in: path
+      name: comment_id
+      schema:
+        type: integer
+      required: true
+      description: Id of the comment.
+      example: 1124
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '403':
+      description: 'Forbidden'
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          example:
+            code: delete_comment_not_authorized
+            summary: Sorry, you are not authorized to delete this comment
+    '404':
+      description: Not Found
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          example:
+            code: not_found
+            summary: Couldn't find Comment with id '1124'
+  tags:
+    - Comments

src/api/public/apidocs-new/paths/comments_package_project_name_package_name.yaml

@@ -0,0 +1,98 @@
+get:
+  summary: List all the package's comments
+  description: List all the comments for the package.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+    - $ref: '../components/parameters/package_name.yaml'
+  responses:
+    '200':
+      description: OK. The request has succeeded.
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/comments.yaml'
+          example: |
+            <comments project="home:Admin" package="0ad">
+              <comment who="Iggy" when="2021-10-15 13:28:22 UTC" id="1">This is a pretty cool comment!</comment>
+            </comments>
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: |
+        Not found.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              summary: 'Package not found: home:Admin/notapackage'
+              value:
+                code: not_found
+                summary: 'Package not found: home:Admin/notapackage'
+  tags:
+    - Comments
+
+post:
+  summary: Create a package comment
+  description: Create a comment for the package.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+    - $ref: '../components/parameters/package_name.yaml'
+    - in: query
+      name: parent_id
+      schema:
+        type: integer
+      description: Id of the comment to reply to
+      example: 10401
+  requestBody:
+    description: Content of the comment
+    required: true
+    content:
+      text/plain:
+        schema:
+          type: string
+        example: This is a very valuable comment
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '400':
+      description: |
+        Invalid Comment.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            invalid_record:
+              summary: Parent belongs to different object
+              value:
+                code: invalid_record
+                summary: Parent belongs to different object
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: |
+        Not found.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              summary: 'Package not found: openSUSE:Factory/eeee'
+              value:
+                code: not_found
+                summary: 'Package not found: openSUSE:Factory/eeee'
+  tags:
+    - Comments

src/api/public/apidocs-new/paths/comments_project_project_name.yaml

@@ -0,0 +1,94 @@
+get:
+  summary: List all the project's comments
+  description: List all the comments for the project.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+  responses:
+    '200':
+      description: OK. The request has succeeded.
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/comments.yaml'
+          example: |
+            <comments project="home:Admin">
+              <comment who="Iggy" when="2021-10-15 13:28:22 UTC" id="1">This is a pretty cool comment!</comment>
+            </comments>
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: |
+        Not found.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              summary: 'Project not found: notaproject'
+              value:
+                code: not_found
+                summary: 'Project not found: notaproject'
+  tags:
+    - Comments
+
+post:
+  summary: Create a project comment
+  description: Create a comment for the project.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+    - in: query
+      name: parent_id
+      schema:
+        type: integer
+      description: Id of the comment to reply to
+      example: 10401
+  requestBody:
+    description: Content of the comment
+    required: true
+    content:
+      text/plain:
+        schema:
+          type: string
+        example: This is a very valuable comment
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '400':
+      description: |
+        Invalid Comment.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            invalid_record:
+              summary: Parent belongs to different object
+              value:
+                code: invalid_record
+                summary: Parent belongs to different object
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: |
+        Not found.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              value:
+                code: not_found
+  tags:
+    - Comments

src/api/public/apidocs-new/paths/comments_request_id.yaml

@@ -0,0 +1,96 @@
+get:
+  summary: List all the request's comments
+  description: List all the comments for the request.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/request.yaml#/RequestId'
+  responses:
+    '200':
+      description: OK. The request has succeeded.
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/comments.yaml'
+          example: |
+            <comments request="115">
+              <comment who="Iggy" when="2021-10-15 13:28:22 UTC" id="1">This is a pretty cool comment!</comment>
+            </comments>
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: |
+        Not found.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              summary: Couldn't find BsRequest with [WHERE `bs_requests`.`number` = ?]
+              value:
+                code: not_found
+                summary: Couldn't find BsRequest with [WHERE `bs_requests`.`number` = ?]
+  tags:
+    - Comments
+
+post:
+  summary: Create a request comment
+  description: Create a comment for the request.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/request.yaml#/RequestId'
+    - in: query
+      name: parent_id
+      schema:
+        type: integer
+      description: Id of the comment to reply to
+      example: 10401
+  requestBody:
+    description: Content of the comment
+    required: true
+    content:
+      text/plain:
+        schema:
+          type: string
+        example: This is a very valuable comment
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '400':
+      description: |
+        Invalid Comment.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            invalid_record:
+              summary: Parent belongs to different object
+              value:
+                code: invalid_record
+                summary: Parent belongs to different object
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: |
+        Not found.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              summary: Couldn't find BsRequest with [WHERE `bs_requests`.`number` = ?]
+              value:
+                code: not_found
+                summary: Couldn't find BsRequest with [WHERE `bs_requests`.`number` = ?]
+  tags:
+    - Comments