Merge pull request #10637 from krauselukas/api_docs/request

Add OpenAPI documentation for request endpoints

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

@@ -10,6 +10,7 @@ tags:
   - name: Person
   - name: Attribute Namespaces
   - name: Attributes
+  - name: Request
 
 info:
   description: Open Build Service API
@@ -61,6 +62,15 @@ paths:
   /person/{login}/token:
     $ref: 'paths/person_login_token.yaml'
 
+  /request:
+    $ref: 'paths/request.yaml'
+  /request?view=collection:
+    $ref: 'paths/request_view_collection.yaml'
+  /request/{id}:
+    $ref: 'paths/request_id.yaml'
+  /request/{id}?cmd=diff:
+    $ref: 'paths/request_id_cmd_diff.yaml'
+
 components:
   securitySchemes:
     basic_authentication:

src/api/public/apidocs-new/components/parameters/request.yaml

@@ -0,0 +1,82 @@
+User:
+  in: query
+  name: user
+  schema:
+    type: string
+  description: |
+    Filter the results of requests and open reviews for a certain user. If no other parameters are
+    applied, it will include requests where the user is maintainer of the target or the creator of
+    the request.
+  example: hans
+Project:
+  in: query
+  name: project
+  schema:
+    type: string
+  description: Limit the results of requests and open review requests to the specified target project.
+  example: home:hans
+Package:
+  in: query
+  name: package
+  schema:
+    type: string
+  description: Limit the results of requests and open review requests to the specified target package.
+  example: ruby
+States:
+  in: query
+  name: states
+  schema:
+    type: string
+  description: Limit results to a given request state. Multiple states can be provided as a comma separated list.
+  example: new,review
+Types:
+  in: query
+  name: types
+  schema:
+    type: string
+  description: Limit the results to certain action types. Multiple types can be provided as a comma separated list.
+  example: add_role,submit
+Roles:
+  in: query
+  name: roles
+  schema:
+    type: string
+  description: Limit the results to a given role. Multiple roles can be provided as a comma separated list.
+  example:
+    creator,maintainer,reviewer,source,target
+WithHistory:
+  in: query
+  name: withhistory
+  schema:
+    type: string
+  description: Include the request history in the results.
+  example: 1
+WithFullHistory:
+  in: query
+  name: withfullhistory
+  schema:
+    type: string
+  description: Includes both, request and review history in the results.
+  example: 1
+Limit:
+  in: query
+  name: limit
+  schema:
+    type: integer
+  description: Limit the results to the specified amount of requests.
+  example: 7
+Ids:
+  in: query
+  name: ids
+  schema:
+    type: string
+  description: Limit the result to specified request id's. Multiple id's can be provided as a comma separated list.
+  example: 15,19,23
+RequestId:
+  in: path
+  name: id
+  schema:
+    type: integer
+  required: true
+  description: Id of the choosen request.
+  example: 743

src/api/public/apidocs-new/components/responses/request.yaml

@@ -0,0 +1,8 @@
+description: |
+  OK.
+
+  XML Schema used for body validation: [request.rng](../schema/request.rng)
+content:
+  application/xml; charset=utf-8:
+    schema:
+      $ref: '../schemas/request/request.yaml'

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

@@ -0,0 +1,13 @@
+type: object
+properties:
+  matches:
+    type: string
+    example: 7
+    xml:
+      attribute: true
+  request:
+    type: array
+    items:
+      $ref: './request.yaml'
+xml:
+  name: 'collection'

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
+