PHRAS-3153_Doc-to-Swagger

- big refacto, split in multiple files

API_documentation/v3/_compiled.yaml

@@ -10,47 +10,10 @@ info:
   license:
     name: GNU GPL V3
     url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
-components:
-  parameters:
-    offsetParam:
-      name: offset
-      in: query
-      description: offset in records count
-      required: false
-      schema:
-        type: integer
-        minimum: 0
-        default: 0
-    limitParam:
-      name: limit
-      in: query
-      description: number of results
-      required: false
-      schema:
-        type: integer
-        minimum: 1
-        maximum: 100
-        default: 10
-    sbas_id:
-      name: sbas_id
-      in: path
-      description: ID of the databox
-      required: true
-      schema:
-        type: integer
-    record_id:
-      name: record_id
-      in: path
-      description: ID of the record
-      required: true
-      schema:
-        $ref: '#/components/parameters/sbas_id/schema'
 paths:
   /me:
     get:
-      description: blabla
+      description: todo
-      servers:
-        - url: 'https://alpha.preprod.alchemyasp.com/api/v1'
       responses:
         '200':
           description: successful operation
@@ -63,7 +26,42 @@ paths:
       description: |
         Fulltext search for records or stories.
 
-        - pagination: use (offset/limit) OR (page/per_page)
+        ## About pagination
+
+        * offset / limit
+
+            offset starts at 0, the unit is "record"
+        * page / per_page
+
+            the first page is 1, per_page is the number of "records" per page.
+
+        so (page=4 ; per_page=5) <===> (offset=15 ; limit=5)
+
+        use (offset/limit) __OR__ (page/per_page)
+
+        ## About "story_children_limit"
+
+        This parameter asks __for each story in the resultset__ to get the __N first__ children (records) of the story.
+
+        example with __N=5__ :
+
+        * If a story contains __3__ children, the story will expose :
+            * children_offset = 0 (always 0 since only first children are returned
+            * children_limit = 5 (copy of the story_children_limit parameter)
+            * children_count = 3 (number or children returned)
+            * children_total = 3 (total number of children in the story)
+
+        * If a story contains __7__ children, the story will expose :
+            * children_offset = 0 (always 0 since only first children are returned
+            * children_limit = 5 (copy of the story_children_limit parameter)
+            * children_count = 5 (number or children returned)
+            * children_total = 7 (total number of children in the story)
+
+        ## About "include(s)"
+
+        To get smaller / faster response, facets and stories children are ommited by default.
+
+        Add _include_ parameters to get those if needed.
       parameters:
         - name: query
           in: query
@@ -83,7 +81,9 @@ paths:
               - 1
             default: 0
           description: |
-            * `0` - search for records * `1` - search for stories
+            search for records or stories
+              * `0` - search for records
+              * `1` - search for stories
         - name: page
           in: query
           description: 'page number, from 1. Use along with "per_page"'
@@ -184,28 +184,7 @@ paths:
                           stories:
                             type: array
                             items:
-                              allOf:
+                              $ref: '#/paths/~1stories~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/responses/200/content/application~1json/schema/properties/response'
-                                - $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response/allOf/0'
-                                - type: object
-                                  properties:
-                                    children_offset:
-                                      type: integer
-                                      description: Children pagination offset ; Always 0
-                                    children_limit:
-                                      type: integer
-                                      description: Children pagination limit ; Equal to "story_children_limit" passed in request
-                                    children_count:
-                                      type: integer
-                                      description: 'Number of children in "children" array ; [0...limit]'
-                                    children_total:
-                                      type: integer
-                                      description: Total number of -visibles for user- children in this story
-                                    children:
-                                      type: array
-                                      items:
-                                        type: object
-                                        items:
-                                          $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response'
                           records:
                             type: array
                             items:
@@ -244,68 +223,24 @@ paths:
                                     description: Formulated query to search items matching this facet
                                     example: 'database:db_demo'
         default:
-          description: Any (other) error
+          description: Any other error
   /searchraw:
     post:
       tags:
         - searchraw
       description: |
-        Fulltext search for records or stories; Returns raw es
+        Fulltext search for records or stories; Returns __raw es documents__
-        - pagination: use (offset/limit) OR (page/per_page)
+
+        Stories children are not returned, use route _stories/.../.../children_
+
+        see pagination description in route _search_
       parameters:
-        - name: query
+        - $ref: '#/paths/~1search/post/parameters/0'
-          in: query
+        - $ref: '#/paths/~1search/post/parameters/1'
-          description: Fulltext query (<empty> = search all)
+        - $ref: '#/paths/~1search/post/parameters/2'
-          required: false
+        - $ref: '#/paths/~1search/post/parameters/3'
-          schema:
+        - $ref: '#/paths/~1search/post/parameters/4'
-            type: string
+        - $ref: '#/paths/~1search/post/parameters/5'
-            example: dogs OR cats
-            default: ''
-        - name: search_type
-          in: query
-          required: false
-          schema:
-            type: integer
-            enum:
-              - 0
-              - 1
-            default: 0
-          description: |
-            search for records or stories
-              * `0` - search for records
-              * `1` - search for stories
-        - name: page
-          in: query
-          description: 'page number, from 1. Use along with "per_page"'
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            default: 1
-        - name: per_page
-          in: query
-          description: number of results per page. Use along with "page"
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
-            default: 10
-        - name: offset
-          in: query
-          description: 'offset in records count, from 0. Use along with "limit"'
-          required: false
-          schema:
-            type: integer
-            minimum: 0
-        - name: limit
-          in: query
-          description: number of results. Use along with "offset"
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
       responses:
         '200':
           description: ok
@@ -349,9 +284,9 @@ paths:
                               type: object
                               properties:
                                 record_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 collection_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 uuid:
                                   type: string
                                   example: dcee40ea-ee26-4d8b-b0c2-d61305b03bc0
@@ -378,7 +313,7 @@ paths:
                                   format: date-time
                                   example: '2021-01-01 15:30:00'
                                 coll_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 collection_name:
                                   type: string
                                   example: collection de test
@@ -392,9 +327,9 @@ paths:
                                   type: integer
                                   example: 5618218
                                 base_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 databox_id:
-                                  $ref: '#/components/parameters/sbas_id/schema'
+                                  $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                 databox_name:
                                   type: string
                                   example: db_databox1
@@ -503,11 +438,22 @@ paths:
       tags:
         - record
       summary: Find record by sbas_id and record_id
-      description: Returns a single record
+      description: |
+        Returns a single record, which can be a real record or a story (check `is_story`)
       operationId: getRecordById
       parameters:
-        - $ref: '#/components/parameters/sbas_id'
+        - name: sbas_id
-        - $ref: '#/components/parameters/record_id'
+          in: path
+          description: ID of the databox
+          required: true
+          schema:
+            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
+        - name: record_id
+          in: path
+          description: ID of the record
+          required: true
+          schema:
+            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
       responses:
         '200':
           description: ok
@@ -545,7 +491,13 @@ paths:
           description: ID of the base
           required: true
           schema:
-            $ref: '#/components/parameters/sbas_id/schema'
+            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
+        - name: base_id
+          in: path
+          description: ID of the base
+          required: true
+          schema:
+            type: integer
       requestBody:
         content:
           multipart/form-data:
@@ -574,7 +526,7 @@ paths:
                           field_name:
                             type: string
                           meta_struct_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           action:
                             type: string
                             enum:
@@ -607,15 +559,30 @@ paths:
                 type: object
                 properties:
                   meta:
-                    $ref: '#/paths/~1search/post/responses/200/content/application~1json/schema/properties/meta'
+                    type: object
+                    properties:
+                      api_version:
+                        type: string
+                      request:
+                        type: string
+                      response_time:
+                        type: string
+                        format: date-time
+                      http_code:
+                        type: integer
+                        format: int32
+                      error_type:
+                        type: string
+                      error_message:
+                        type: string
                   response:
                     allOf:
                       - type: object
                         properties:
                           databox_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           record_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           title:
                             type: string
                           original_name:
@@ -627,9 +594,9 @@ paths:
                             type: string
                             format: date-time
                           collection_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           base_id:
-                            $ref: '#/components/parameters/sbas_id/schema'
+                            $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                           thumbnail:
                             type: object
                             properties:
@@ -642,7 +609,7 @@ paths:
                                     type: string
                                     format: date-time
                                   id:
-                                    $ref: '#/components/parameters/sbas_id/schema'
+                                    $ref: '#/paths/~1records~1%7Bbase_id%7D/post/parameters/1/schema'
                                   is_activated:
                                     type: boolean
                                   label:
@@ -1059,18 +1026,8 @@ paths:
         ```
       operationId: patchRecord
       parameters:
-        - name: sbas_id
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/0'
-          in: path
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/1'
-          description: ID of the sbas
-          required: true
-          schema:
-            $ref: '#/components/parameters/sbas_id/schema'
-        - name: record_id
-          in: path
-          description: ID of the record
-          required: true
-          schema:
-            $ref: '#/components/parameters/sbas_id/schema'
       requestBody:
         content:
           application/json:
@@ -1086,6 +1043,60 @@ paths:
                 $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema'
         default:
           $ref: '#/paths/~1search/post/responses/default'
+  '/stories/{sbas_id}/{record_id}':
+    get:
+      tags:
+        - story
+      summary: Find a story (record) by sbas_id and record_id
+      description: |
+        Returns a single story
+
+        This is the __same__ parameters / result as _/records/..._, except that here the record __must__ be a story else 404 is returned
+      operationId: getRecordById
+      parameters:
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/0'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/1'
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  meta:
+                    $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/meta'
+                  response:
+                    allOf:
+                      - $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response/allOf/0'
+                      - type: object
+                        properties:
+                          children_offset:
+                            type: integer
+                            description: Children pagination offset ; Always 0
+                            example: 0
+                          children_limit:
+                            type: integer
+                            description: Children pagination limit ; Equal to "story_children_limit" passed in request
+                            example: 10
+                          children_count:
+                            type: integer
+                            description: 'Number of children in "children" array ; [0...limit]'
+                            example: 5
+                          children_total:
+                            type: integer
+                            description: Total number of __visibles for user__ children in this story
+                            example: 5
+                          children:
+                            type: array
+                            items:
+                              type: object
+                              items:
+                                $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/response'
+        '404':
+          description: Story not found (
+        default:
+          $ref: '#/paths/~1search/post/responses/default'
   '/stories/{sbas_id}/{record_id}/children':
     get:
       tags:
@@ -1094,8 +1105,8 @@ paths:
       description: Returns children of a story
       operationId: getStoryChildren
       parameters:
-        - $ref: '#/components/parameters/sbas_id'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/0'
-        - $ref: '#/components/parameters/record_id'
+        - $ref: '#/paths/~1records~1%7Bsbas_id%7D~1%7Brecord_id%7D/get/parameters/1'
         - name: page
           in: query
           description: page number (default 1)
@@ -1117,7 +1128,7 @@ paths:
                 type: object
                 properties:
                   meta:
-                    $ref: '#/paths/~1search/post/responses/200/content/application~1json/schema/properties/meta'
+                    $ref: '#/paths/~1records~1%7Bbase_id%7D/post/responses/200/content/application~1json/schema/properties/meta'
                   response:
                     type: array
                     items:

API_documentation/v3/common.yaml

@@ -0,0 +1,79 @@
+  ApiResponse_meta:
+    type: object
+    properties:
+      api_version:
+        type: string
+      request:
+        type: string
+      response_time:
+        type: string
+        format: date-time
+      http_code:
+        type: integer
+        format: int32
+      error_type:
+        type: string
+      error_message:
+        type: string
+
+  Facet:
+    type: object
+    properties:
+      name:
+        type: string
+        description: 'Unique internal name (=key) for the facet'
+        example: '_base'
+      field:
+        type: string
+        description: 'Source field (from db structure). Can be also virtual field like "database" '
+        example: 'database'
+      values:
+        type: array
+        items:
+          type: object
+          properties:
+            value:
+              type: string
+              description: 'Human readable value for the value'
+              example: 'Demo'
+            raw_value:
+              type: string
+              description: 'Real value, to be used to query'
+              example: 'db_demo'
+            count:
+              type: integer
+              description: 'Number of items matching this value'
+            query:
+              type: string
+              description: 'Formulated query to search items matching this facet'
+              example: 'database:db_demo'
+
+  PermalinkObject:
+    type: object
+    properties:
+      created_on:
+        type: string
+        format: date-time
+      id:
+        $ref: '#/ID'
+      is_activated:
+        type: boolean
+      label:
+        type: string
+      updated_on:
+        type: string
+        format: date-time
+      page_url:
+        type: string
+      download_url:
+        type: string
+      url:
+        type: string
+
+  FacetsArray:
+    type: array
+    items:
+      $ref: '#/Facet'
+
+  ID:
+    type: integer

API_documentation/v3/es.yaml

@@ -0,0 +1,175 @@
+ESRecord:
+  description: 'Raw response from es search on "record" index/mapping'
+  type: object
+  properties:
+    _index:
+      type: string
+      description: 'ES index'
+      example:
+        'phraseanet_dxmpcw3y8td68f+h_20201124161735.910647'
+    _type:
+      type: string
+      description: 'Data type'
+      example:
+        'record'
+    _id:
+      type: string
+      description: 'unique id of document (sbas_id + "_" + record_id)'
+      example:
+        '1_555'
+    _version:
+      type: integer
+      description: 'auto-increment at each indexation of the document'
+      example:
+        1
+    _score:
+      type: number
+      description: 'score of the document related to a whole resultset'
+      example:
+        1
+    _source:
+      $ref: '#/ESRecordSource'
+
+ESRecordSource:
+  type: object
+  properties:
+    record_id:
+      $ref: 'common.yaml#/ID'
+    collection_id:
+      $ref: 'common.yaml#/ID'
+    uuid:
+      type: string
+      example:
+        'dcee40ea-ee26-4d8b-b0c2-d61305b03bc0'
+    flags_bitfield:
+      type: integer
+    sha256:
+      type: string
+      example:
+        '7fad283de349b903c850548cda65cf2d86d24c4e3856cdc2b97e47430494b8c8'
+    original_name:
+      type: string
+      example:
+        '1134340545.jpg'
+    mime:
+      type: string
+      example:
+        'image/jpeg'
+    type:
+      type: string
+      example:
+        'image'
+    created_on:
+      type: string
+      format: date-time
+      example:
+        '2020-12-07 09:48:01'
+    updated_on:
+      type: string
+      format: date-time
+      example:
+        '2021-01-01 15:30:00'
+    coll_id:
+      $ref: 'common.yaml#/ID'
+    collection_name:
+      type: string
+      example:
+        'collection de test'
+    witdh:
+      type: integer
+      example:
+        5616
+    height:
+      type: integer
+      example:
+        3744
+    size:
+      type: integer
+      example:
+        5618218
+    base_id:
+      $ref: 'common.yaml#/ID'
+    databox_id:
+      $ref: 'common.yaml#/ID'
+    databox_name:
+      type: string
+      example:
+        'db_databox1'
+    record_type:
+      type: string
+      enum: ['record','story']
+    title:
+      type: object
+      description: 'key->value list, where (key) is the lng, and (value) the title in this lng.'
+      additionalProperties: true
+      example:
+        fr: 'titre en Français'
+        en: 'title in english'
+        '': 'undefined-lng title ? To be fixed'
+    metadata_tags:
+      type: object
+      description: 'key->value list, where (key) is the name of the metadata, and (value) the value.'
+      additionalProperties: true
+      example:
+        Channels: 3
+        ColorDepth: 8
+        ColorSpace: 0
+        FileSize: 5618218
+        Height: 3744
+        MimeType: 'image/jpeg'
+        Width: 5616
+    caption:
+      type: object
+      description: >
+        'key->value list, where (key) is the field name, and (value) the value(s).'
+
+        'nb: mono-valued field value is a 1 element array.'
+      additionalProperties:
+        type: array
+        items:
+          type: string
+      example:
+        Artist: ['Bob']
+        Title: ['Cropped Hand Of Person Holding Computer Mouse']
+        Keywords: ['Hand', 'Mouse (computer)']
+    caption_all:
+      type: array
+      items:
+        type: string
+      description: >
+        'all fields values in a single array'
+      example: ['Bob','Cropped Hand Of Person Holding Computer Mouse','Hand','Mouse (computer)']
+    flags:
+      $ref: '#/Flags'
+    subdefs:
+      type: object
+      description: 'key->value list, where (key) is the name of the subdef, and (value) is the subdef object.'
+      additionalProperties:
+        type: object
+      example:
+        document:
+          type: object
+          properties:
+            width: 5616
+            height: 3744
+            size: 5618218
+            mime: 'image/jpeg'
+            permalink: 'http://localhost/permalink/v1/2/34/document/1134340545.jpg?token=xrdMnK6peB...'
+        thumbnail:
+          type: object
+          properties:
+            width: 1024
+            height: 683
+            size: 20011
+            mime: 'image/jpeg'
+            permalink: 'http://localhost/permalink/v1/2/34/preview/1134340545.jpg?token=E5aSbXQTmAz...'
+
+Flags:
+  type: object
+  description: 'key->value list, where (key) is the name of the flag (=status bit), and (value) is the boolean value.'
+  additionalProperties:
+    type: boolean
+  example:
+    public: true
+    color_checked: true
+    embargo: false

API_documentation/v3/parameters.yaml

@@ -0,0 +1,88 @@
+sbas_id:
+  name: sbas_id
+  in: path
+  description: ID of the databox
+  required: true
+  schema:
+    $ref: common.yaml#/ID
+
+base_id:
+  name: base_id
+  in: path
+  description: ID of the base
+  required: true
+  schema:
+    $ref: common.yaml#/ID
+
+record_id:
+  name: record_id
+  in: path
+  description: ID of the record
+  required: true
+  schema:
+    $ref: common.yaml#/ID
+
+query:
+  name: query
+  in: query
+  description: 'Fulltext query (<empty> = search all)'
+  required: false
+  schema:
+    type: string
+    example: 'dogs OR cats'
+    default: ''
+
+search_type:
+  name: search_type
+  in: query
+  required: false
+  schema:
+    type: integer
+    enum: [0,1]
+    default: 0
+  description: >
+    search for records or stories
+      * `0` - search for records
+      * `1` - search for stories
+
+page:
+  name: page
+  in: query
+  description: page number, from 1. Use along with "per_page"
+  required: false
+  schema:
+    type: integer
+    minimum: 1
+    default: 1
+
+per_page:
+  name: per_page
+  in: query
+  description: number of results per page. Use along with "page"
+  required: false
+  schema:
+    type: integer
+    minimum: 1
+    maximum: 100
+    default: 10
+
+offset:
+  name: offset
+  in: query
+  description: offset in records count, from 0. Use along with "limit"
+  required: false
+  schema:
+    type: integer
+    minimum: 0
+    # default: 0
+
+limit:
+  name: limit
+  in: query
+  description: number of results. Use along with "offset"
+  required: false
+  schema:
+    type: integer
+    minimum: 1
+    maximum: 100
+    # default:

API_documentation/v3/record.yaml

@@ -0,0 +1,119 @@
+  _Record_:
+    type: object
+    properties:
+      databox_id:
+        $ref: 'common.yaml#/ID'
+      record_id:
+        $ref: 'common.yaml#/ID'
+      title:
+        type: string
+      original_name:
+        type: string
+      updated_on:
+        type: string
+        format: date-time
+      created_on:
+        type: string
+        format: date-time
+      collection_id:
+        $ref: 'common.yaml#/ID'
+      base_id:
+        $ref: 'common.yaml#/ID'
+      thumbnail:
+        $ref: '#/Subdef'
+      uuid:
+        type: string
+
+  Record:
+    allOf:     # Combines the basic _Record_ and the records-only properties
+      - $ref: '#/_Record_'
+      - type: object
+        properties:
+          mime_type:
+            type: string
+          technical_informations:
+            type: array
+            items:
+              $ref: '#/TechnicalInformation'
+          sha256:
+            type: string
+          phrasea_type:
+            type: string
+            enum:
+              - image
+              - video
+
+  Story:
+    allOf:     # Combines the basic _Record_ and the stories-only properties
+      - $ref: '#/_Record_'
+      - type: object
+        properties:
+          children_offset:
+            type: integer
+            description: 'Children pagination offset ; Always 0'
+            example: 0
+          children_limit:
+            type: integer
+            description: 'Children pagination limit ; Equal to "story_children_limit" passed in request'
+            example: 10
+          children_count:
+            type: integer
+            description: 'Number of children in "children" array ; [0...limit]'
+            example: 5
+          children_total:
+            type: integer
+            description: 'Total number of __visibles for user__ children in this story'
+            example: 5
+          children:
+            type: array
+            items:
+              type: object
+              items:
+                $ref: '#/Record'
+
+  TechnicalInformation:
+    type: object
+    properties:
+      name:
+        type: string
+      value:
+        type: string
+
+  Subdef:
+    type: object
+    properties:
+      name:
+        type: string
+      permalink:
+        $ref: 'common.yaml#/PermalinkObject'
+      height:
+        type: integer
+      width:
+        type: integer
+      filesize:
+        type: integer
+      devices:
+        type: array
+        items:
+          type: string
+          enum:
+            - screen
+            - printer ?
+      player_type:
+        type: string
+        enum:
+          - IMAGE
+      mime_type:
+        type: string
+      substituted:
+        type: boolean
+      created_on:
+        type: string
+        format: date-time
+      updated_on:
+        type: string
+        format: date-time
+      url:
+        type: string
+      url_ttl:
+        type: integer

API_documentation/v3/responses.yaml

@@ -12,4 +12,4 @@ record_response:
         404:
             description: Record not found
 error_response:
-        description: Any (other) error
+        description: Any other error

API_documentation/v3/schemas.yaml

@@ -4,7 +4,7 @@ RecordPatch_metadata:
         field_name:
             type: string
         meta_struct_id:
-            $ref: '#/ID'
+            $ref: 'common.yaml#/ID'
         action:
             type: string
             enum:
@@ -64,46 +64,16 @@ ApiResponse_record:
         meta:
             $ref: '#/ApiResponse_meta'
         response:
-            $ref: '#/Record'
+            $ref: 'record.yaml#/Record'
-
+ApiResponse_story:
-# -------------------- searchraw ---------------
-ApiResponse_searchraw:
     type: object
     properties:
         meta:
             $ref: '#/ApiResponse_meta'
         response:
-            $ref: '#/ApiResponse_searchraw_response'
+            $ref: 'record.yaml#/Story'
-ApiResponse_searchraw_response:
+
-    type: object
+# -------------------- searchraw ---------------
-    properties:
-        results:
-            type: array
-            items:
-                $ref: '#/ESRecord'
-        took:
-            type: integer
-            description: 'Search duration in msec'
-            example:
-                12
-#        offset:
-#            type: integer
-#            description: 'Pagination offset as passed (or computed from "page/per_page") in request'
-#        limit:
-#            type: integer
-#            description: 'Pagination limit as passed in request'
-        count:
-            type: integer
-            description: 'Number of results in this page [0...limit]'
-            example:
-                1
-        total:
-            type: integer
-            description: 'Total number of results'
-            example:
-                1
-        facets:
-            $ref: '#/FacetsArray'
 
 # -------------------- search ---------------
 ApiResponse_search:
@@ -135,330 +105,15 @@ ApiResponse_search_response:
                 stories:
                     type: array
                     items:
-                        $ref: '#/Story'
+                        $ref: 'record.yaml#/Story'
                 records:
                     type: array
                     items:
-                        $ref: '#/Record'
+                        $ref: 'record.yaml#/Record'
         facets:
-            $ref: '#/FacetsArray'
+            $ref: 'common.yaml#/FacetsArray'
 
 
-ID:
-    type: integer
-
-Permalink:
-    type: object
-    properties:
-        created_on:
-            type: string
-            format: date-time
-        id:
-            $ref: '#/ID'
-        is_activated:
-            type: boolean
-        label:
-            type: string
-        updated_on:
-            type: string
-            format: date-time
-        page_url:
-            type: string
-        download_url:
-            type: string
-        url:
-            type: string
-
-Subdef:
-    type: object
-    properties:
-        name:
-            type: string
-        permalink:
-            $ref: '#/Permalink'
-        height:
-            type: integer
-        width:
-            type: integer
-        filesize:
-            type: integer
-        devices:
-            type: array
-            items:
-                type: string
-                enum:
-                    - screen
-                    - printer ?
-        player_type:
-            type: string
-            enum:
-                - IMAGE
-        mime_type:
-            type: string
-        substituted:
-            type: boolean
-        created_on:
-            type: string
-            format: date-time
-        updated_on:
-            type: string
-            format: date-time
-        url:
-            type: string
-        url_ttl:
-            type: integer
-
-TechnicalInformation:
-    type: object
-    properties:
-        name:
-            type: string
-        value:
-            type: string
-_Record_:
-    type: object
-    properties:
-        databox_id:
-            $ref: '#/ID'
-        record_id:
-            $ref: '#/ID'
-        title:
-            type: string
-        original_name:
-            type: string
-        updated_on:
-            type: string
-            format: date-time
-        created_on:
-            type: string
-            format: date-time
-        collection_id:
-            $ref: '#/ID'
-        base_id:
-            $ref: '#/ID'
-        thumbnail:
-            $ref: '#/Subdef'
-        uuid:
-            type: string
-
-ESRecord:
-    description: 'Raw response from es search on "record" index/mapping'
-    type: object
-    properties:
-        _index:
-            type: string
-            description: 'ES index'
-            example:
-                'phraseanet_dxmpcw3y8td68f+h_20201124161735.910647'
-        _type:
-            type: string
-            description: 'Data type'
-            example:
-                'record'
-        _id:
-            type: string
-            description: 'unique id of document (sbas_id + "_" + record_id)'
-            example:
-                '1_555'
-        _version:
-            type: integer
-            description: 'auto-increment at each indexation of the document'
-            example:
-                1
-        _score:
-            type: number
-            description: 'score of the document related to a whole resultset'
-            example:
-                1
-        _source:
-            $ref: '#/ESRecordSource'
-
-ESRecordSource:
-    type: object
-    properties:
-        record_id:
-            $ref: '#/ID'
-        collection_id:
-            $ref: '#/ID'
-        uuid:
-            type: string
-            example:
-                'dcee40ea-ee26-4d8b-b0c2-d61305b03bc0'
-        flags_bitfield:
-            type: integer
-        sha256:
-            type: string
-            example:
-                '7fad283de349b903c850548cda65cf2d86d24c4e3856cdc2b97e47430494b8c8'
-        original_name:
-            type: string
-            example:
-                '1134340545.jpg'
-        mime:
-            type: string
-            example:
-                'image/jpeg'
-        type:
-            type: string
-            example:
-                'image'
-        created_on:
-            type: string
-            format: date-time
-            example:
-                '2020-12-07 09:48:01'
-        updated_on:
-            type: string
-            format: date-time
-            example:
-                '2021-01-01 15:30:00'
-        coll_id:
-            $ref: '#/ID'
-        collection_name:
-            type: string
-            example:
-                'collection de test'
-        witdh:
-            type: integer
-            example:
-                5616
-        height:
-            type: integer
-            example:
-                3744
-        size:
-            type: integer
-            example:
-                5618218
-        base_id:
-            $ref: '#/ID'
-        databox_id:
-            $ref: '#/ID'
-        databox_name:
-            type: string
-            example:
-                'db_databox1'
-        record_type:
-            type: string
-            enum: ['record','story']
-        title:
-            type: object
-            description: 'key->value list, where (key) is the lng, and (value) the title in this lng.'
-            additionalProperties: true
-            example:
-                fr: 'titre en Français'
-                en: 'title in english'
-                '': 'undefined-lng title ? To be fixed'
-        metadata_tags:
-            type: object
-            description: 'key->value list, where (key) is the name of the metadata, and (value) the value.'
-            additionalProperties: true
-            example:
-                Channels: 3
-                ColorDepth: 8
-                ColorSpace: 0
-                FileSize: 5618218
-                Height: 3744
-                MimeType: 'image/jpeg'
-                Width: 5616
-        caption:
-            type: object
-            description: >
-                'key->value list, where (key) is the field name, and (value) the value(s).'
-
-                'nb: mono-valued field value is a 1 element array.'
-            additionalProperties:
-                type: array
-                items:
-                    type: string
-            example:
-                Artist: ['Bob']
-                Title: ['Cropped Hand Of Person Holding Computer Mouse']
-                Keywords: ['Hand', 'Mouse (computer)']
-        caption_all:
-            type: array
-            items:
-                type: string
-            description: >
-                'all fields values in a single array'
-            example: ['Bob','Cropped Hand Of Person Holding Computer Mouse','Hand','Mouse (computer)']
-        flags:
-            $ref: '#/Flags'
-        subdefs:
-            type: object
-            description: 'key->value list, where (key) is the name of the subdef, and (value) is the subdef object.'
-            additionalProperties:
-                type: object
-            example:
-                document:
-                    type: object
-                    properties:
-                        width: 5616
-                        height: 3744
-                        size: 5618218
-                        mime: 'image/jpeg'
-                        permalink: 'http://localhost/permalink/v1/2/34/document/1134340545.jpg?token=xrdMnK6peB...'
-                thumbnail:
-                    type: object
-                    properties:
-                        width: 1024
-                        height: 683
-                        size: 20011
-                        mime: 'image/jpeg'
-                        permalink: 'http://localhost/permalink/v1/2/34/preview/1134340545.jpg?token=E5aSbXQTmAz...'
-
-Flags:
-    type: object
-    description: 'key->value list, where (key) is the name of the flag (=status bit), and (value) is the boolean value.'
-    additionalProperties:
-        type: boolean
-    example:
-        public: true
-        color_checked: true
-        embargo: false
-
-Record:
-    allOf:     # Combines the basic _Record_ and the records-only properties
-        - $ref: '#/_Record_'
-        - type: object
-          properties:
-            mime_type:
-                type: string
-            technical_informations:
-                type: array
-                items:
-                    $ref: '#/TechnicalInformation'
-            sha256:
-                type: string
-            phrasea_type:
-                type: string
-                enum:
-                    - image
-                    - video
-
-Story:
-    allOf:     # Combines the basic _Record_ and the stories-only properties
-        - $ref: '#/_Record_'
-        - type: object
-          properties:
-            children_offset:
-                type: integer
-                description: 'Children pagination offset ; Always 0'
-            children_limit:
-                type: integer
-                description: 'Children pagination limit ; Equal to "story_children_limit" passed in request'
-            children_count:
-                type: integer
-                description: 'Number of children in "children" array ; [0...limit]'
-            children_total:
-                type: integer
-                description: 'Total number of -visibles for user- children in this story'
-            children:
-                type: array
-                items:
-                    type: object
-                    items:
-                        $ref: '#/Record'
 
 RecordUri:
     type: string
@@ -477,38 +132,3 @@ ApiResponse_RecordsUriArray:
         response:
             $ref: '#/RecordsUriArray'
 
-Facet:
-    type: object
-    properties:
-        name:
-            type: string
-            description: 'Unique internal name (=key) for the facet'
-            example: '_base'
-        field:
-            type: string
-            description: 'Source field (from db structure). Can be also virtual field like "database" '
-            example: 'database'
-        values:
-            type: array
-            items:
-                type: object
-                properties:
-                    value:
-                        type: string
-                        description: 'Human readable value for the value'
-                        example: 'Demo'
-                    raw_value:
-                        type: string
-                        description: 'Real value, to be used to query'
-                        example: 'db_demo'
-                    count:
-                        type: integer
-                        description: 'Number of items matching this value'
-                    query:
-                        type: string
-                        description: 'Formulated query to search items matching this facet'
-                        example: 'database:db_demo'
-FacetsArray:
-    type: array
-    items:
-        $ref: '#/Facet'

API_documentation/v3/search.yaml

@@ -0,0 +1,39 @@
+
+  ApiResponse_search:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/ApiResponse_search_response'
+
+  ApiResponse_search_response:
+    type: object
+    properties:
+      offset:
+        type: integer
+        description: 'Pagination offset as passed (or computed from "page/per_page") in request'
+      limit:
+        type: integer
+        description: 'Pagination limit as passed in request'
+      count:
+        type: integer
+        description: 'Number of results in this page [0...limit]'
+      total:
+        type: integer
+        description: 'Total number of results'
+        minimum: 1
+      results:
+        type: object
+        properties:
+          stories:
+            type: array
+            items:
+              $ref: 'record.yaml#/Story'
+          records:
+            type: array
+            items:
+              $ref: 'record.yaml#/Record'
+      facets:
+        $ref: 'common.yaml#/FacetsArray'
+

API_documentation/v3/searchraw.yaml

@@ -0,0 +1,38 @@
+ApiResponse_searchraw:
+  type: object
+  properties:
+    meta:
+      $ref: 'common.yaml#/ApiResponse_meta'
+    response:
+      $ref: '#/ApiResponse_searchraw_response'
+
+ApiResponse_searchraw_response:
+  type: object
+  properties:
+    results:
+      type: array
+      items:
+        $ref: 'es.yaml#/ESRecord'
+    took:
+      type: integer
+      description: 'Search duration in msec'
+      example:
+        12
+    #        offset:
+    #            type: integer
+    #            description: 'Pagination offset as passed (or computed from "page/per_page") in request'
+    #        limit:
+    #            type: integer
+    #            description: 'Pagination limit as passed in request'
+    count:
+      type: integer
+      description: 'Number of results in this page [0...limit]'
+      example:
+        1
+    total:
+      type: integer
+      description: 'Total number of results'
+      example:
+        1
+    facets:
+      $ref: 'common.yaml#/FacetsArray'