Merge pull request #10650 from eduardoj/document_issue_trackers_with_…

…openapi

Document '/issue_trackers' API routes with OpenAPI

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

@@ -6,6 +6,7 @@ servers:
 tags:
   - name: General Information
   - name: Groups
+  - name: Issue Trackers
   - name: Person
   - name: Attribute Namespaces
   - name: Attributes
@@ -47,6 +48,13 @@ paths:
   /group/{group_title}:
     $ref: 'paths/group_group_title.yaml'
 
+  /issue_trackers:
+    $ref: 'paths/issue_trackers.yaml'
+  /issue_trackers/{issue_tracker_name}:
+    $ref: 'paths/issue_trackers_issue_tracker_name.yaml'
+  /issue_trackers/{issue_tracker_name}/issues/{issue_name}:
+    $ref: 'paths/issue_trackers_issue_tracker_name_issues_issue_name.yaml'
+
   /person:
     $ref: 'paths/person.yaml'
 

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

@@ -0,0 +1,7 @@
+in: path
+name: issue_name
+schema:
+  type: string
+required: true
+description: Issue name.
+example: 12345

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

@@ -0,0 +1,7 @@
+in: path
+name: issue_tracker_name
+schema:
+  type: string
+required: true
+description: Issue tracker name
+example: fate

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

@@ -0,0 +1,22 @@
+type: object
+properties:
+  created_at:
+    type: string
+    example: '2021-01-18 19:17:51 UTC'
+  updated_at:
+    type: string
+    example: '2021-01-18 19:17:51 UTC'
+  name:
+    type: string
+    example: 12345
+  tracker:
+    type: string
+    example: fate
+  label:
+    type: string
+    example: 'fate#12345'
+  url:
+    type: string
+    example: 'https://features.opensuse.org/12345'
+xml:
+  name: issue

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

@@ -0,0 +1,28 @@
+type: object
+properties:
+  name:
+    type: string
+    example: fate
+  kind:
+    type: string
+    example: fate
+  description:
+    type: string
+    example: openSUSE Feature Database
+  url:
+    type: string
+    example: 'https://features.opensuse.org/'
+  show-url:
+    type: string
+    example: 'https://features.opensuse.org/@@@'
+  regex:
+    type: string
+    example: '(?:fate|Fate|FATE)\s*#\s*(\d+)'
+  label:
+    type: string
+    example: 'fate#@@@'
+  enable-fetch:
+    type: string
+    example: 'false'
+xml:
+  name: issue-tracker

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

@@ -0,0 +1,7 @@
+type: array
+items:
+  $ref: 'issue_tracker.yaml'
+xml:
+  name: issue-trackers
+  wrapped: true
+

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

@@ -0,0 +1,62 @@
+get:
+  summary: Get the list of issue trackers.
+  description: Get the list of issue trackers.
+  security:
+    - basic_authentication: []
+  responses:
+    '200':
+      description: |
+        List of issue trackers.
+
+        XML Schema used for body validation: [issue_trackers.rng](../schema/issue_trackers.rng)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/list_issue_trackers.yaml'
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+  tags:
+    - Issue Trackers
+
+post:
+  summary: Create an issue tracker.
+  description: Create an issue tracker.
+  security:
+    - basic_authentication: []
+  requestBody:
+    description: |
+      Issue tracker definition.
+
+      XML Schema used for body validation: [issue_tracker.rng](../schema/issue_tracker.rng)
+    required: true
+    content:
+      application/xml; charset=utf-8:
+        schema:
+          $ref: '../components/schemas/issue_tracker.yaml'
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '400':
+      description: |
+        Validation failed.
+
+        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:
+            empty_body:
+              value:
+                code: validation_failed
+                summary: Document is empty, not allowed for issue_tracker
+              summary: Empty Body
+            wrong_xml_element:
+              value:
+                code: validation_failed
+                summary: 'issue_tracker validation error: 1:0: ERROR: Expecting element issue-tracker, got foo'
+              summary: Wrong XML Element
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+  tags:
+    - Issue Trackers

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

@@ -0,0 +1,105 @@
+get:
+  summary: Show an issue tracker.
+  description: Show an issue tracker.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/issue_tracker_name.yaml'
+  responses:
+    '200':
+      description: |
+        Issue tracker definition.
+
+        XML Schema used for body validation: [issue_tracker.rng](../schema/issue_tracker.rng)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/issue_tracker.yaml'
+    '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'
+          example:
+            code: not_found
+            summary: Unable to find issue tracker 'foo'
+  tags:
+    - Issue Trackers
+
+put:
+  summary: Update or create an issue tracker.
+  description: Update the issue tracker given as path parameter. If it is not found, create it.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/issue_tracker_name.yaml'
+  requestBody:
+    description: |
+      Issue tracker definition.
+
+      XML Schema used for body validation: [issue_tracker.rng](../schema/issue_tracker.rng)
+    required: true
+    content:
+      application/xml; charset=utf-8:
+        schema:
+          $ref: '../components/schemas/issue_tracker.yaml'
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '400':
+      description: |
+        Validation failed.
+
+        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:
+            empty_body:
+              value:
+                code: validation_failed
+                summary: Document is empty, not allowed for issue_tracker
+              summary: Empty Body
+            wrong_xml_element:
+              value:
+                code: validation_failed
+                summary: 'issue_tracker validation error: 1:0: ERROR: Expecting element issue-tracker, got foo'
+              summary: Wrong XML Element
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+  tags:
+    - Issue Trackers
+
+delete:
+  summary: Delete an issue tracker.
+  description: Delete an issue tracker.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/issue_tracker_name.yaml'
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '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'
+          example:
+            code: not_found
+            summary: Unable to find issue tracker 'foo'
+  tags:
+    - Issue Trackers

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

@@ -0,0 +1,34 @@
+get:
+  summary: Show an issue of an issue tracker.
+  description: Show an issue of an issue tracker.
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/issue_name.yaml'
+  responses:
+    '200':
+      description: |
+        Issue definition.
+
+        XML Schema used for body validation: [issue.rng](../schema/issue.rng)
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/issue.yaml'
+    '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'
+          example:
+            code: issue_tracker_not_found
+            summary: Error: Issue Tracker 'foo' not found.
+  tags:
+    - Issue Trackers
+