Merge pull request #398 from Toloka/openapi-fix

Fixes for OpenAPI files
Toloka · Jun 27, 2023 · 287e723 · 287e723
2 parents 7de61cc + 27abcc8
commit 287e723
Show file tree

Hide file tree

Showing 2 changed files with 221 additions and 45 deletions.
diff --git a/en/api/reference/fullApi.yaml b/en/api/reference/fullApi.yaml
@@ -2557,7 +2557,7 @@ paths:
           description: |
             The operation ID for asynchronously loading one or more task suites (if `async_mode=true`).
 
-            We recommend sending the ID in the `POST` request to avoid accidental errors, such as creating the operation multiple times for the same task suites.
+            <aside class="warning">We recommend sending <code>operation_id</code> in the <code>POST</code> request to avoid accidental errors, such as creating the operation multiple times for the same task suites.</aside>
 
             The ID should conform to the [RFC4122 standard](https://tools.ietf.org/html/rfc4122).
 
@@ -2901,7 +2901,7 @@ paths:
           description: |
             The operation ID for a scheduled upload of one or more tasks (if `async_mode=true` is set).
 
-            We recommended sending the ID in the `POST` request to avoid accidental errors, such as creating the operation multiple times for the same tasks.
+            <aside class="warning">We recommend sending <code>operation_id</code> in the <code>POST</code> request to avoid accidental errors, such as creating the operation multiple times for the same tasks.</aside>
 
             The ID should conform to the [RFC4122 standard](https://tools.ietf.org/html/rfc4122).
 
@@ -5889,12 +5889,28 @@ components:
             The balance type. Possible values:
 
             - `BEST_CONCURRENT_USERS_BY_QUALITY` — Active Tolokers with access to the task.
-            - `TOP_PERCENTAGE_BY_QUALITY` — Users with the best task completion quality.
+            - `TOP_PERCENTAGE_BY_QUALITY` — Tolokers with the best task completion quality.
           enum:
             - BEST_CONCURRENT_USERS_BY_QUALITY
             - TOP_PERCENTAGE_BY_QUALITY
-      discriminator:
-        propertyName: type
+        count:
+          maximum: 100
+          minimum: 0
+          type: integer
+          format: int64
+          description: |
+            The field is used together with the balance `type` set to `BEST_CONCURRENT_USERS_BY_QUALITY`.
+
+            The number of active Tolokers the task is available to.
+        percent:
+          maximum: 100
+          minimum: 10
+          type: integer
+          format: int32
+          description: |
+            The field is used together with the balance `type` set to `TOP_PERCENTAGE_BY_QUALITY`.
+
+            The percentage of Tolokers with the best task completion quality. Possible values are **10**, **20**, **30**, **40**...**100**.
     ActionConfigDtoV1:
       required:
         - parameters
@@ -6035,7 +6051,7 @@ components:
               description: |
                 **Required** if dynamic overlap is used.
 
-                The maximum overlap. Must be higher than the values in `defaults`. Minimum — 1. Maximum — 30000.
+                The maximum overlap. Must be higher than the values in `defaults`.
               format: int64
             min_confidence:
               maximum: 1
@@ -6044,7 +6060,7 @@ components:
               description: |
                 **Required** if dynamic overlap is used.
 
-                The minimum confidence of the aggregated response. Values from 0 to 1.
+                The minimum confidence of the aggregated response.
             answer_weight_skill_id:
               type: string
               description: |
@@ -6061,18 +6077,6 @@ components:
                 Don't specify several fields if their values depend on each other.
               items:
                 $ref: '#/components/schemas/Field'
-    BestConcurrentUsersCherryPickingConfig:
-      type: object
-      allOf:
-        - $ref: '#/components/schemas/AbstractUsersCherryPickingConfig'
-        - type: object
-          properties:
-            count:
-              maximum: 100
-              minimum: 0
-              type: integer
-              format: int64
-              description: The number of active Tolokers the task is available to. The field is shown if the balance type is set to `BEST_CONCURRENT_USERS_BY_QUALITY`.
     CheckpointsConfig:
       type: object
       description: |
@@ -6270,7 +6274,7 @@ components:
           minimum: 0
           type: integer
           description: |
-            The waiting time (in seconds) after adding a task or increasing the overlap before assigning the last task suite in the pool. Minimum — 0, maximum — 86,400 seconds (one day).
+            The waiting time (in seconds) after adding a task or increasing the overlap before assigning the last task suite in the pool. Minimum — **0**, maximum — **86,400** seconds (one day).
 
             This parameter can be used if the pool has `force_last_assignment` set to `true`.
           format: int32
@@ -6284,7 +6288,7 @@ components:
             The number of control tasks per suite.
           format: int32
         golden_task_distribution_function:
-          $ref: '#/components/schemas/TaskDistributionFunction'
+          $ref: './parts/api/additional.yaml#/components/schemas/GoldenTaskDistributionFunction'
         min_golden_tasks_count:
           maximum: 500
           minimum: 0
@@ -6340,7 +6344,7 @@ components:
             The number of training tasks per suite.
           format: int32
         training_task_distribution_function:
-          $ref: '#/components/schemas/TaskDistributionFunction'
+          $ref: './parts/api/additional.yaml#/components/schemas/TrainingTaskDistributionFunction'
     OneFieldConditionDtoV1:
       required:
         - key
@@ -6378,12 +6382,12 @@ components:
           description: |
             The comparison operator (the `key` data is compared with the threshold value from `value`):
 
-            - `EQ` (Equal) — Equal to.
-            - `GT` (Greater than) — Greater than.
-            - `GTE` (Greater than equal to) — Greater than or equal to.
-            - `LT` (Less than) — Less than.
-            - `LTE` (Less than equal to) — Less than or equal to.
-            - `NE` (Not equal to) — Not equal to.
+            - `EQ` — Equal to.
+            - `GT` — Greater than.
+            - `GTE` — Greater than or equal to.
+            - `LT` — Less than.
+            - `LTE` — Less than or equal to.
+            - `NE` — Not equal to.
           enum:
             - EQ
             - GT
@@ -6471,7 +6475,7 @@ components:
           default: 0
           type: integer
           description: |
-            The waiting time (in seconds) before automatic closure of the pool after all tasks are completed. Minimum — `0`, maximum — `259,200` seconds (three days).
+            The waiting time (in seconds) before automatic closure of the pool after all tasks are completed. Minimum — **0**, maximum — **259,200** seconds (three days).
 
             Use it if:
 
@@ -6483,7 +6487,7 @@ components:
           minimum: 0
           type: number
           description: |
-            The payment per task suite in U.S. dollars. For cents, use the dot (`"."`) as the separator. The minimum payment is $0.01.
+            The payment per task suite in U.S. dollars. For cents, use the dot (`"."`) as the separator. The minimum payment is **$0.01**.
 
             Only training and control tasks can be uploaded to zero-price pools.
         dynamic_pricing_config:
@@ -6609,7 +6613,7 @@ components:
           $ref: '#/components/schemas/ActionConfigDtoV1'
         conditions:
           type: array
-          description: Conditions (for example, _10 task suites skipped in a row_). Multiple conditions are combined with the "OR" operator.
+          description: Conditions (for example, _10 task suites skipped in a row_). Multiple conditions are combined with the `AND` operator.
           items:
             $ref: '#/components/schemas/OneFieldConditionDtoV1'
     Settings:
@@ -6638,7 +6642,7 @@ components:
       description: |
         **Required** if selective review is used.
 
-        The distribution of tasks with selective review. More information about [how verification tasks are assigned](https://toloka.ai/docs/guide/pool-main/).
+        The distribution of tasks with selective review. More information about [how verification tasks are assigned](https://toloka.ai/docs/guide/selective-mvote/).
       properties:
         distribution:
           type: string
@@ -6681,18 +6685,6 @@ components:
 
             The period in which completed tasks are counted (number of days).
           format: int64
-    TopPercentageUsersCherryPickingConfig:
-      type: object
-      allOf:
-        - $ref: '#/components/schemas/AbstractUsersCherryPickingConfig'
-        - type: object
-          properties:
-            percent:
-              maximum: 100
-              minimum: 10
-              type: integer
-              format: int32
-              description: The percentage of Tolokers with the best task completion quality. The field is shown if the balance type is set to `TOP_PERCENTAGE_BY_QUALITY`. Possible values are 10, 20, 30, 40...100.
     TrainingConfig:
       type: object
       description: Additional settings for linked training.
@@ -6757,7 +6749,7 @@ components:
           type: integer
           format: int64
           description: |
-            The waiting time (in seconds) before automatic closure of the pool after all tasks are completed. Minimum — `0`, maximum — `259,200` seconds (three days).
+            The waiting time (in seconds) before automatic closure of the pool after all tasks are completed. Minimum — **0**, maximum — **259,200** seconds (three days).
 
             Use it if:
 

diff --git a/en/api/reference/parts/api/additional.yaml b/en/api/reference/parts/api/additional.yaml
@@ -419,11 +419,47 @@ components:
         - $ref: '../../fullApi.yaml#/components/schemas/Settings'
         - type: object
           description: Selective review of control tasks. To make sure selective review is enabled, don't forget to set up display of this type of task in `mixer_config`.
+          properties:
+            task_distribution_function:
+              allOf:
+                - $ref: '#/components/schemas/GoldenTaskDistributionFunction'
+                - type: object
+                  properties:
+                    distribution:
+                      description: |
+                        **Required** if selective review is used.
+
+                        The distribution of control tasks with selective review within an interval.
+                    intervals:
+                      description: |
+                        **Required** if selective review is used.
+
+                        Interval limits and frequency of control tasks with selective review.
+                      items:
+                        $ref: '#/components/schemas/GoldenTaskSelectiveInterval'
     TrainingSettings:
       allOf:
         - $ref: '../../fullApi.yaml#/components/schemas/Settings'
         - type: object
           description: Selective review of training tasks. To make sure selective review is enabled, don't forget to set up display of this type of task in `mixer_config`.
+          properties:
+            task_distribution_function:
+              allOf:
+                - $ref: '#/components/schemas/TrainingTaskDistributionFunction'
+                - type: object
+                  properties:
+                    distribution:
+                      description: |
+                        **Required** if selective review is used.
+
+                        The distribution of training tasks with selective review within an interval.
+                    intervals:
+                      description: |
+                        **Required** if selective review is used.
+
+                        Interval limits and frequency of training tasks with selective review.
+                      items:
+                        $ref: '#/components/schemas/TrainingTaskSelectiveInterval'
     HasMore:
       type: boolean
       description: |
@@ -465,3 +501,151 @@ components:
 
                 The frequency of tasks with selective review within an interval. The first task in an interval is a majority vote task. For example, if you set `frequency: 3`, then tasks number `1`, `4`, `7`, and so on, will be majority vote tasks.
               format: int32
+    GoldenTaskInterval:
+      allOf:
+        - $ref: '#/components/schemas/QualityControlInterval'
+        - type: object
+          properties:
+            from:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                The start of the interval (the number of tasks completed by a Toloker in the project or in the pool).
+            to:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                The end of the interval (the number of tasks completed by a Toloker in the project or in the pool).
+            frequency:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                The frequency of control tasks in an interval. The first task in an interval is a control task. For example, if you set `frequency: 3`, then tasks number `1`, `4`, `7` and so on will be control tasks.
+    GoldenTaskSelectiveInterval:
+      allOf:
+        - $ref: '#/components/schemas/QualityControlInterval'
+        - type: object
+          properties:
+            from:
+              description: |
+                **Required** if selective review is used.
+
+                The start of the interval (the number of tasks completed by a Toloker in the project or in the pool).
+            to:
+              description: |
+                **Required** if selective review is used.
+
+                The end of the interval (the number of tasks completed by a Toloker in the project or in the pool).
+            frequency:
+              description: |
+                **Required** if selective review is used.
+
+                The frequency of control tasks with selective review within an interval. The first task in an interval is a majority vote task. For example, if you set `frequency: 3`, then tasks number `1`, `4`, `7` and so on will be majority vote tasks.
+    TrainingTaskInterval:
+      allOf:
+        - $ref: '#/components/schemas/QualityControlInterval'
+        - type: object
+          properties:
+            from:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                The start of the interval (number of tasks completed by the Toloker in the project or in the pool).
+            to:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                The end of the interval (the number of tasks completed by a Toloker in the project or in the pool).
+            frequency:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                The frequency of training tasks in an interval. The first task in an interval is a training task. For example, if you set `frequency: 3`, then tasks number `1`, `4`, `7` and so on will be training tasks.
+    TrainingTaskSelectiveInterval:
+      allOf:
+        - $ref: '#/components/schemas/QualityControlInterval'
+        - type: object
+          properties:
+            from:
+              description: |
+                **Required** if selective review is used.
+
+                The start of the interval (number of tasks completed by the Toloker in the project or in the pool).
+            to:
+              description: |
+                **Required** if selective review is used.
+
+                The end of the interval (the number of tasks completed by a Toloker in the project or in the pool).
+            frequency:
+              description: |
+                **Required** if selective review is used.
+
+                The frequency of training tasks with selective review within an interval. The first task in an interval is a majority vote task. For example, if you set `frequency: 3`, then tasks number `1`, `4`, `7` and so on will be majority vote tasks.
+    GoldenTaskDistributionFunction:
+      allOf:
+        - $ref: '../../fullApi.yaml#/components/schemas/TaskDistributionFunction'
+        - type: object
+          description: |
+            Vary the frequency of control tasks. The option allows you to change the frequency of checking as the Toloker completes more tasks.
+
+            If it is filled in, use `real_task_count` to specify the maximum number of tasks per task suite. To use the option, set the `golden_task_count:0` and `min_golden_tasks_count:null` parameter values.
+          properties:
+            distribution:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                The distribution of control tasks within an interval.
+            intervals:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                The interval boundaries and the number of control tasks in an interval.
+              items:
+                $ref: '#/components/schemas/GoldenTaskInterval'
+            scope:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                How to count tasks completed by the Toloker:
+
+                - `POOL` — Count the completed pool tasks.
+                - `PROJECT` — Count the completed project tasks.
+            window_days:
+              description: |
+                **Required** if control tasks are assigned at a variable rate.
+
+                The period in which completed tasks are counted (number of days).
+    TrainingTaskDistributionFunction:
+      allOf:
+        - $ref: '../../fullApi.yaml#/components/schemas/TaskDistributionFunction'
+        - type: object
+          description: |
+            Issue training tasks with uneven frequency. This option allows you to change the frequency of training tasks as the Toloker completes more tasks.
+
+            If it is filled in, then in `real_task_count` specify the maximum number of tasks to put in a task suite. To use the option, set parameter values `training_task_count:0` and `min_training_tasks_count:null`.
+          properties:
+            distribution:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                The distribution of training tasks within an interval.
+            intervals:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                The interval boundaries and the number of training tasks in an interval.
+              items:
+                $ref: '#/components/schemas/TrainingTaskInterval'
+            scope:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                How to count tasks completed by the Toloker:
+
+                - `POOL` — Count the completed pool tasks.
+                - `PROJECT` — Count the completed project tasks.
+            window_days:
+              description: |
+                **Required** if training tasks are assigned at a variable rate.
+
+                The period in which completed tasks are counted (number of days).