Add OpenAPI documentation for request diff endpoint

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

@@ -68,6 +68,8 @@ paths:
     $ref: 'paths/request_request_collection.yaml'
   /request/{id}:
     $ref: 'paths/request_request_id.yaml'
+  /request/{id}?cmd=diff:
+    $ref: 'paths/request_request_diff.yaml'
 
 components:
   securitySchemes:

src/api/public/apidocs-new/components/schemas/request/diff.yaml

@@ -0,0 +1,178 @@
+type: object
+properties:
+  id:
+    type: string
+    example: 12
+    xml:
+      attribute: true
+  actions:
+    type: string
+    example: 0
+    xml:
+      attribute: true
+  action:
+    type: object
+    properties:
+      type:
+        type: string
+        example: submit
+        xml:
+          attribute: true
+      source:
+        type: object
+        properties:
+          project:
+            type: string
+            example: 'home:Iggy:branches:home:Admin'
+            xml:
+              attribute: true
+          package:
+            type: string
+            example: ruby
+            xml:
+              attribute: true
+          rev:
+            type: string
+            example: 3
+            xml:
+              attribute: true
+      target:
+        type: object
+        properties:
+          project:
+            type: string
+            example: 'home:Admin'
+            xml:
+              attribute: true
+          package:
+            type: string
+            example: ruby
+            xml:
+              attribute: true
+      options:
+        type: object
+        properties:
+          sourceupdate:
+            example: cleanup
+            type: string
+      sourcediff:
+        type: object
+        properties:
+          key:
+            type: string
+            example: '9dbe9eb1767c5e12c69839af893dc239'
+            xml:
+              attribute: true
+          old:
+            $ref: '#/components/schemas/NewOldDestination'
+          new:
+            $ref: '#/components/schemas/NewOldDestination'
+          files:
+            type: array
+            items:
+              type: object
+              properties:
+                file:
+                  type: object
+                  properties:
+                    state:
+                      type: string
+                      example: changed
+                      xml:
+                        attribute: true
+                    old:
+                      $ref: '#/components/schemas/OldNewFile'
+                    new:
+                      $ref: '#/components/schemas/OldNewFile'
+                    diff:
+                      # FIXME: 'lines' attribute missing due to https://github.com/OAI/OpenAPI-Specification/issues/630
+                      type: string
+                      example: |
+                        spec files:
+                        -----------
+                        --- test.spec
+                        +++ test.spec
+                        @@ -0,0 +1 @@
+                        +# NEW COMMENT
+                        \ No newline at end of file
+          issues:
+            type: array
+            items:
+              type: object
+              properties:
+                issue:
+                  type: object
+                  properties:
+                    state:
+                      type: string
+                      example: 'added'
+                      xml:
+                        attribute: true
+                    tracker:
+                      type: string
+                      example: bnc
+                      xml:
+                        attribute: true
+                    name:
+                      type: string
+                      example: 922894
+                      xml:
+                        attribute: true
+                    label:
+                      type: string
+                      example: 'boo#944302'
+                      xml:
+                        attribute: true
+                    url:
+                      type: string
+                      example: 'https://bugzilla.opensuse.org/show_bug.cgi?id=944302'
+                      xml:
+                        attribute: true
+
+components:
+  schemas:
+    NewOldDestination:
+      type: object
+      properties:
+        project:
+          type: string
+          example: 'home:Iggy:branches:home:Admin'
+          xml:
+            attribute: true
+        package:
+          type: string
+          example: ruby
+          xml:
+            attribute: true
+        rev:
+          type: string
+          example: 3
+          xml:
+            attribute: true
+        srcmd5:
+          type: string
+          example: '59300f4ba65f53334b2e2a39f87ba3a0'
+          xml:
+            attribute: true
+
+    OldNewFile:
+      type: object
+      properties:
+        name:
+          type: string
+          example: 'ruby.spec'
+          xml:
+            attribute: true
+        md5:
+          type: string
+          example: 'd4f573d2bf9a0e306f87dad7eee0cf56'
+          xml:
+            attribute: true
+        size:
+          type: string
+          example: 70
+          xml:
+            attribute: true
+xml:
+  name: diff
+

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

@@ -0,0 +1,61 @@
+post:
+  summary: Get the diff for all packages affected by the request.
+  description: |
+    Get the diff for all packages affected by the request.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/request.yaml#/RequestId'
+    - in: query
+      name: diff_to_superseded
+      type: integer
+      description: |
+        Diff relative to a given superseded request. State the id of the corresponding superseded request.
+      example: 10401
+    - in: query
+      name: view
+      schema:
+        type: string
+        enum:
+          - xml
+      description: Set this parameter to xml in order to receive a structured diff instead of plain text.
+    - in: query
+      name: withissues
+      schema:
+        type: string
+        enum:
+          - true
+          - 1
+      description: Include parsed issues
+  responses:
+    '200':
+      description: OK
+      content:
+        text/plain; charset=utf-8:
+          schema:
+            type: string
+          example: |
+            spec files:
+            -----------
+            --- test.spec
+            +++ test.spec
+            @@ -0,0 +1 @@
+            +# NEW COMMENT
+            \ No newline at end of file
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/request/diff.yaml'
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '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 request with id '355'
+  tags:
+    - Request
+

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

@@ -0,0 +1,63 @@
+post:
+  summary: Get the diff for all packages affected by the request.
+  description: |
+    Get the diff for all packages affected by the request.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/request.yaml#/RequestId'
+    - in: query
+      name: diff_to_superseded
+      type: integer
+      description: |
+        Diff relative to a given superseded request. State the id of the corresponding superseded request.
+      example: 10401
+    - in: query
+      name: view
+      schema:
+        type: string
+        enum:
+          - xml
+      description: Set this parameter to xml in order to receive a structured diff instead of plain text.
+    - in: query
+      name: withissues
+      schema:
+        type: boolean
+        enum:
+          - true
+          - 1
+      description: Include parsed issues
+  responses:
+    '200':
+      description: OK
+      content:
+        text/plain; charset=utf-8:
+          schema:
+            type: string
+          example: |
+            spec files:
+            -----------
+            --- test.spec
+            +++ test.spec
+            @@ -0,0 +1 @@
+            +# NEW COMMENT
+            \ No newline at end of file
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/request/diff.yaml'
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: Not Found
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            not_found:
+              value:
+                code: not_found
+                summary: Couldn't find request with id '355'
+  tags:
+    - Request
+