PHRAS-3607 : apiv3 doc : add bases[]

fix mismatch record_id / story_id

doc/API_documentation/v3/api.yaml

@@ -110,6 +110,21 @@ components:
         minimum: 1
         maximum: 100
         # default:
+
+    bases:
+      name: bases
+      in: query
+      description: >
+        'bases_id s to search on as seen in `Collection id ("base_id" API side)` in _admin > Databases > ... collection_
+
+        If not set: search all collections'
+      required: false
+      schema:
+        type: array
+        uniqueItems: false
+        items:
+          type: integer
+
 #  securitySchemes:
 #      api_key:
 #          type: apiKey
@@ -123,14 +138,14 @@ components:
 #                  tokenUrl: azea
 
 paths:
-  '/me':
+#  '/me':
-    get:
+#    get:
-      description: 'todo'
+#      description: 'todo'
-      responses:
+#      responses:
-        200:
+#        200:
-          description: successful operation
+#          description: successful operation
-        default:
+#        default:
-          description: Any error
+#          description: Any error
 
   # ---------------- search ----------------
   '/search':
@@ -464,6 +479,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/query'
         - $ref: '#/components/parameters/search_type'
+        - $ref: '#/components/parameters/bases'
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
         - $ref: '#/components/parameters/offset'
@@ -488,7 +504,21 @@ paths:
               type: string
               enum:
                 - facets
+                - suggestions
                 - result.stories.children
+                - results.records.subdefs
+                - results.stories.subdefs
+                - results.records.caption
+                - results.stories.caption
+                - results.records.metadata
+                - results.stories.metadata
+                - results.records.status
+                - results.stories.status
+                - results.records.children
+                - results.records.children.subdefs
+                - results.records.children.caption
+                - results.records.children.metadata
+                - results.records.children.status
       responses:
         200:
           description: ok
@@ -513,6 +543,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/query'
         - $ref: '#/components/parameters/search_type'
+        - $ref: '#/components/parameters/bases'
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
         - $ref: '#/components/parameters/offset'

doc/API_documentation/v3/record.yaml

@@ -5,10 +5,6 @@
         type: integer
         example:
           2
-      record_id:
-        type: integer
-        example:
-          34
       updated_on:
         type: string
         format: date-time
@@ -80,13 +76,19 @@
 
   Record:
     allOf:     # Combines the basic _Record_ and the records-only properties
-      - $ref: '#/_Record_'
       - type: object
         properties:
           record_id:
             type: integer
             example:
               34
+      - $ref: '#/_Record_'
+      - type: object
+        properties:
+#          record_id:
+#            type: integer
+#            example:
+#              34
           mime_type:
             type: string
             example:
@@ -133,15 +135,15 @@
       - $ref: '#/_record_extension_'
 
 
-  Story:
+  _Story_:
     allOf:     # Combines the basic _Record_ and the stories-only properties
       - $ref: '#/_Record_'
       - type: object
         properties:
-          story_id:
+#          story_id:
-            type: integer
+#            type: integer
-            example:
+#            example:
-              1400
+#              1400
           cover_record_id:
             $ref: 'common.yaml#/ID'
             description: 'id of the record chosen as "cover" (or null)'
@@ -182,13 +184,37 @@
               items:
                 $ref: '#/Record'
 
+  StoryWithStoryId:
+    allOf:
+      - type: object
+        properties:
+          story_id:
+            type: integer
+            example:
+              1400
+      - $ref: '#/_Story_'
+
+  StoryWithRecordId:
+    allOf:
+      - type: object
+        properties:
+          record_id:
+            type: integer
+            example:
+              1400
+      - $ref: '#/_Story_'
+
   Story_extended:
     allOf:
-      - $ref: '#/Story'
+      - type: object
+        properties:
+          record_id: # on route /stories, the story has a record_id !!!
+            type: integer
+            example:
+              1400
+      - $ref: '#/StoryWithRecordId'
       - $ref: '#/_record_extension_'
 
-
-
   TechnicalInformation:
     type: object
     additionalProperties:
@@ -289,7 +315,14 @@
       meta:
         $ref: 'common.yaml#/ApiResponse_meta'
       response:
-        $ref: '#/Story'
+        allOf:
+          - type: object
+            properties:
+              record_id:    # on route /stories, the story has a record_id !!!
+                type: integer
+                example:
+                  1400
+          - $ref: '#/StoryWithRecordId'
 
   ApiResponse_story_extended:
     type: object

doc/API_documentation/v3/search.yaml

@@ -29,7 +29,7 @@
           stories:
             type: array
             items:
-              $ref: 'record.yaml#/Story'
+              $ref: 'record.yaml#/StoryWithStoryId'
           records:
             type: array
             items: