PHRAS-3153_Doc-to-Swagger

- add extended mode to /record and /story
- fix compilation in 1 file
- better examples
- todo : extended mode for /search
- todo : check "include[]" available keys (compare with extended mode)
- todo : remove 'id' type ?

API_documentation/v3/_HowTo_Swagger.md

@@ -13,7 +13,7 @@ to update in swaggerhub (single file) :
 
 - compile sources in a single file for swaggerhub (run from <phraseanet-dir>)
 
-    `swagger-cli bundle API_documentation/v3/api.yaml -o API_documentation/v3/_compiled.yaml -t yaml`
+    `swagger-cli bundle API_documentation/v3/api.yaml -r -o API_documentation/v3/_compiled.yaml -t yaml`
 
 
 - copy/paste the generated content from `_compiled.yaml` to

API_documentation/v3/api.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.0
+openapi: 3.0.3
 info:
   description: >
     This is the documentation of Phraseanet API (v3)
@@ -82,7 +82,7 @@ components:
     per_page:
       name: per_page
       in: query
-      description: number of results per page. Use along with "page"
+      description: number of items per page. Use along with "page"
       required: false
       schema:
         type: integer
@@ -93,7 +93,7 @@ components:
     offset:
       name: offset
       in: query
-      description: offset in records count, from 0. Use along with "limit"
+      description: offset in items unit count, from 0. Use along with "limit"
       required: false
       schema:
         type: integer
@@ -103,7 +103,7 @@ components:
     limit:
       name: limit
       in: query
-      description: number of results. Use along with "offset"
+      description: number of items. Use along with "offset"
       required: false
       schema:
         type: integer
@@ -213,7 +213,7 @@ paths:
               schema:
                 $ref: 'search.yaml#/ApiResponse_search'
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'
 
   # ---------------- searchraw ----------------
   '/searchraw':
@@ -241,7 +241,7 @@ paths:
               schema:
                 $ref: 'searchraw.yaml#/ApiResponse_searchraw'
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'
 
   # ------------ record -----------
   '/records/{sbas_id}/{record_id}':
@@ -251,6 +251,15 @@ paths:
       summary: Find record by sbas_id and record_id
       description: |
         Returns a single record, which can be a real record or a story (check `is_story`)
+
+        ## About extended mode
+        passing header `Accept: application/vnd.phraseanet.record-extended+json`
+        will add/populate objects :
+        - subdefs
+        - status
+        - metadata
+        - dces
+
       operationId: getRecordById
       parameters:
         - $ref: '#/components/parameters/sbas_id'
@@ -261,11 +270,14 @@ paths:
           content:
             application/json:
               schema:
-                $ref: schemas.yaml#/ApiResponse_record
+                $ref: record.yaml#/ApiResponse_record
+            'application/vnd.phraseanet.record-extended+json':
+              schema:
+                $ref: record.yaml#/ApiResponse_record_extended
         404:
           description: Record not found
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'
 
   '/records/{base_id}':
     post:
@@ -314,9 +326,9 @@ paths:
           content:
             application/json:
               schema:
-                $ref: schemas.yaml#/ApiResponse_record
+                $ref: record.yaml#/ApiResponse_record
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'
       # security:
       #   - api_key: []
 
@@ -684,9 +696,9 @@ paths:
           content:
             application/json:
               schema:
-                $ref: schemas.yaml#/ApiResponse_record
+                $ref: record.yaml#/ApiResponse_record
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'
 
   '/stories/{sbas_id}/{record_id}':
     get:
@@ -696,7 +708,8 @@ paths:
       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
+        This is the __same__ parameters / result as _/records/..._, (including "extended mode"),
+        except that here the record __must__ be a story else 404 is returned
 
       operationId: getStoryById
       parameters:
@@ -708,11 +721,14 @@ paths:
           content:
             application/json:
               schema:
-                $ref: schemas.yaml#/ApiResponse_story
+                $ref: record.yaml#/ApiResponse_story
+            'application/vnd.phraseanet.record-extended+json':
+              schema:
+                $ref: record.yaml#/ApiResponse_story_extended
         404:
           description: Story not found (
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'
 
 
   '/stories/{sbas_id}/{record_id}/children':
@@ -725,26 +741,18 @@ paths:
       parameters:
         - $ref: '#/components/parameters/sbas_id'
         - $ref: '#/components/parameters/record_id'
-        - name: page
+        - $ref: '#/components/parameters/page'
-          in: query
+        - $ref: '#/components/parameters/per_page'
-          description: page number (default 1)
+        - $ref: '#/components/parameters/offset'
-          required: false
+        - $ref: '#/components/parameters/limit'
-          schema:
-            type: integer
-        - name: per_page
-          in: query
-          description: number of children (records uri) per page (default 10)
-          required: false
-          schema:
-            type: integer
       responses:
         200:
           description: ok
           content:
             application/json:
               schema:
-                $ref: schemas.yaml#/ApiResponse_RecordsUriArray
+                $ref: record.yaml#/ApiResponse_RecordsUriArray
         404:
           description: Story (record) not found
         default:
-          $ref: 'responses.yaml#/error_response'
+          $ref: 'common.yaml#/error_response'

API_documentation/v3/common.yaml

@@ -1,20 +1,43 @@
+  error_response:
+    description: Any other error
+
   ApiResponse_meta:
     type: object
     properties:
       api_version:
         type: string
+        example:
+          '3.0.0'
       request:
         type: string
+        example:
+          'GET|POST|... /api/v3/....'
       response_time:
         type: string
         format: date-time
+        example:
+          '2021-02-11T14:18:02+00:00'
       http_code:
         type: integer
         format: int32
+        example:
+          200
       error_type:
         type: string
+        example:
+          null
       error_message:
         type: string
+        example:
+          null
+      error_details:
+        type: string
+        example:
+          null
+      charset:
+        type: string
+        example:
+          'UTF-8'
 
   Facet:
     type: object
@@ -77,3 +100,14 @@
 
   ID:
     type: integer
+
+  Metadata_value:
+    type: object
+    properties:
+      meta_id:
+        type: integer
+        example: 1771
+      value:
+        type: string
+        example: value_of_the_field
+

API_documentation/v3/record.yaml

@@ -2,13 +2,13 @@
     type: object
     properties:
       databox_id:
-        $ref: 'common.yaml#/ID'
+        type: integer
+        example:
+          2
       record_id:
-        $ref: 'common.yaml#/ID'
+        type: integer
-      title:
+        example:
-        type: string
+          34
-      original_name:
-        type: string
       updated_on:
         type: string
         format: date-time
@@ -16,13 +16,67 @@
         type: string
         format: date-time
       collection_id:
-        $ref: 'common.yaml#/ID'
+        type: integer
+        example:
+          5
       base_id:
-        $ref: 'common.yaml#/ID'
+        type: integer
+        example:
+          14
       thumbnail:
-        $ref: '#/Subdef'
+        $ref: '#/Thumbnail'
       uuid:
         type: string
+        example:
+          '5b079f33-0851-4aec-a978-b7f8d7204e5a'
+
+  _record_extension_:
+    type: object
+    properties:
+      subdefs:
+        type: array
+        items:
+          $ref: '#/Subdef'
+      status:
+        type: array
+        items:
+          type: object
+          properties:
+            bit:
+              type: integer
+              example: 4
+            state:
+              type: boolean
+              example: false
+      metadata:
+        type: array
+        items:
+          type: object
+          properties:
+            meta_structure_id:
+              type: integer
+            name:
+              type: string
+            labels:
+              type: object
+              additionalProperties:
+                type: string
+              example:
+                fr: label_du_champ_en_français
+                en: field_label_in_english
+            value:
+              oneOf:
+                - $ref: 'common.yaml#/Metadata_value'
+                - type: array
+                  items:
+                    $ref: 'common.yaml#/Metadata_value'
+      dces:
+        type: array
+        items:
+          type: string
+          example:
+            '_not_documented_TODO_'
+
 
   Record:
     allOf:     # Combines the basic _Record_ and the records-only properties
@@ -31,23 +85,58 @@
         properties:
           mime_type:
             type: string
+            example:
+              'image/jpeg'
+          title:
+            type: string
+            example:
+              'Sleepy cat'
+          original_name:
+            type: string
+            example:
+              'DSC_12345.jpg'
           technical_informations:
             type: array
             items:
               $ref: '#/TechnicalInformation'
           sha256:
             type: string
+            example:
+              '6f330ac0ae2...'
           phrasea_type:
             type: string
             enum:
               - image
               - video
+            example:
+              'image'
+          is_story:
+            type: boolean
+            default: false
+
+  Record_extended:
+    allOf:
+      - $ref: '#/Record'
+      - $ref: '#/_record_extension_'
 
   Story:
     allOf:     # Combines the basic _Record_ and the stories-only properties
       - $ref: '#/_Record_'
       - type: object
         properties:
+          mime_type:
+            type: string
+            default: null
+          title:
+            type: string
+            example:
+              'sans-titre'
+          original_name:
+            type: string
+            default: null
+          is_story:
+            type: boolean
+            default: true
           children_offset:
             type: integer
             description: 'Children pagination offset ; Always 0'
@@ -71,13 +160,23 @@
               items:
                 $ref: '#/Record'
 
+  Story_extended:
+    allOf:
+      - $ref: '#/Story'
+      - $ref: '#/_record_extension_'
+
+
+
   TechnicalInformation:
     type: object
-    properties:
+    additionalProperties:
-      name:
+      type: string
-        type: string
+    example:
-      value:
+      Aperture: 6.3
-        type: string
+      CameraModel: 'Canon EOS 5D Mark II'
+      Channels: 3
+      ColorSpace: RGB
+      FileSize: 5618218
 
   Subdef:
     type: object
@@ -107,6 +206,7 @@
         type: string
       substituted:
         type: boolean
+        example: false
       created_on:
         type: string
         format: date-time
@@ -117,3 +217,77 @@
         type: string
       url_ttl:
         type: integer
+        example: 7200
+
+  Thumbnail:
+    allOf:
+      - type: object
+        properties:
+          name:
+            example: 'thumbnail'
+          mime_type:
+            example: 'image/jpeg'
+          height:
+            example: 160
+          width:
+            example: 240
+          filesize:
+            example: 2375
+          url:
+            example: 'http://phraseanet.demo.fr/medias/eyJ0eXAiOiJKV1Q...'
+      - $ref: '#/Subdef'
+
+  ApiResponse_record:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/Record'
+
+  ApiResponse_record_extended:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/Record_extended'
+
+  ApiResponse_story:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/Story'
+
+  ApiResponse_story_extended:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/Story_extended'
+
+
+  # for "/stories/{sbas_id}/{record_id}/children"
+  RecordUri:
+    type: string
+    example: '/api/v3/records/1/48'
+
+  RecordsUriArray:
+    type: array
+    items:
+      $ref: '#/RecordUri'
+    example:
+      - '/api/v3/records/1/48'
+      - '/api/v3/records/1/49'
+      - '/api/v3/records/1/50'
+  ApiResponse_RecordsUriArray:
+    type: object
+    properties:
+      meta:
+        $ref: 'common.yaml#/ApiResponse_meta'
+      response:
+        $ref: '#/RecordsUriArray'
+

API_documentation/v3/responses.yaml

@@ -1,15 +0,0 @@
-record_response:
-    type: object
-    properties:
-        200:
-            description: successful operation
-            content:
-                application/json:
-                    schema:
-                        $ref: schemas.yaml#/ApiResponse_record
-        400:
-            description: Any other error
-        404:
-            description: Record not found
-error_response:
-        description: Any other error

API_documentation/v3/schemas.yaml

@@ -41,94 +41,9 @@ RecordPatch:
             type: array
             items:
                 $ref: '#/RecordPatch_status'
-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
-ApiResponse_record:
-    type: object
-    properties:
-        meta:
-            $ref: '#/ApiResponse_meta'
-        response:
-            $ref: 'record.yaml#/Record'
-ApiResponse_story:
-    type: object
-    properties:
-        meta:
-            $ref: '#/ApiResponse_meta'
-        response:
-            $ref: 'record.yaml#/Story'
-
 # -------------------- searchraw ---------------
 
 # -------------------- search ---------------
-ApiResponse_search:
-    type: object
-    properties:
-        meta:
-            $ref: '#/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'
 
 
 
-RecordUri:
-    type: string
-    example:
-        '/api/v3/records/1/48'
-RecordsUriArray:
-    type: array
-    items:
-        $ref: '#/RecordUri'
-
-ApiResponse_RecordsUriArray:
-    type: object
-    properties:
-        meta:
-            $ref: '#/ApiResponse_meta'
-        response:
-            $ref: '#/RecordsUriArray'
-