Merge pull request #91 from regulaforensics/7938-matching-update

Added descriptions, enum members

Author: KirylKovaliov

common.yml

@@ -394,7 +394,7 @@ components:
           $ref: "#/components/schemas/FaceSDKResultCode"
 
     ImageData:
-      description: "Base64 encoded image."
+      description: "Base64-encoded image."
       type: string
       format: byte
 
@@ -449,7 +449,17 @@ components:
 
     FaceSDKResultCode:
       type: integer
-      description: "The result code, see enum: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/"
+      description: "The result code, see the [FaceSDKResultCode enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/).
+      
+      Some of the values: 
+      
+      - `0`—everything is OK
+
+      - `1`—image is empty, try again with another image
+
+      - `2`—face is not detected
+
+      - `6`—data cannot be decoded as an image"
       enum:
         - 0
         - 1
@@ -490,6 +500,8 @@ components:
         - 250
         - 251
         - 252
+        - 253
+        - 254
       x-enum-varnames:
         - FACER_OK
         - FR_IMAGE_EMPTY
@@ -530,11 +542,12 @@ components:
         - FACER_TIMEOUT_LIVENESS_TRANSACTION
         - FACER_FAILED_LIVENESS_TRANSACTION
         - FACER_ABORTED_LIVENESS_TRANSACTION
+        - FACER_GENERAL_ERROR
+        - FACER_PASSIVE_LIVENESS_FAIL
 
     Thumbnail:
-      description: "Base64 of the cropped portrait."
-      type: string
-      format: byte
+      description: "See `crop` instead."
+      deprecated: true
 
     FaceRectangular:
       description: "The rectangular area of a detected face that is represented by a set of four elements: the X and Y coordinates of the top-left point, and the width and height dimensions of the rectangle."

detect.yml

@@ -1,14 +1,13 @@
 openapi: 3.0.3
-
-
 paths:
   /detect:
     parameters:
       - $ref: './common.yml#/components/parameters/x-request'
     post:
       tags:
         - matching
-      summary: "Detect face, evaluate attributes, assess the portrait quality"
+      summary: "detect faces"
+      description: "Detect face, evaluate attributes, assess the portrait quality"      
       operationId: detect
       requestBody:
         required: true
@@ -33,7 +32,7 @@ components:
       properties:
         tag:
           type: string
-          description: "Session identificator."
+          description: "Session identificator, should be unique for each session."
         processParam:
           $ref: "./common.yml#/components/schemas/ProcessParam"
         image:

identification.yml

@@ -60,7 +60,7 @@ components:
       properties:
         name:
           type: string
-          description: "Person name."
+          description: "Person's name."
         metadata:
           type: object
           additionalProperties: true
@@ -77,7 +77,7 @@ components:
       properties:
         name:
           type: string
-          description: "Person name."
+          description: "Person's name."
         metadata:
           type: object
           additionalProperties: true
@@ -95,7 +95,7 @@ components:
       properties:
         tag:
           type: string
-          description: "Session identificator."
+          description: "Session identificator, should be unique for each session."
         image:
           type: object
           description: "Uploaded image."

index.yml

@@ -1,12 +1,22 @@
 openapi: 3.0.3
 info:
   version: 6.1.0
-  title: Regula FaceSDK Web API
+  title: Regula Face SDK Web API
   x-logo:
     url: 'https://static-content.regulaforensics.com/Icons/Logos/Regula-logo.svg'
     href: 'https://mobile.regulaforensics.com/'
   description: |
-    [Download OpenAPI specification](https://github.com/regulaforensics/FaceSDK-web-openapi)
+    <a href="https://regulaforensics.com/products/face-recognition-sdk/  " target="_blank">Regula Face SDK</a> is a cross-platform biometric verification solution for a digital identity verification process. The SDK enables convenient and reliable face capture on the client side (mobile, web, and desktop) and further processing on the client or server side.
+
+    The Face SDK includes the following features:
+    
+    * <a href="https://docs.regulaforensics.com/develop/face-sdk/overview/introduction/#face-detection" target="_blank">Face Detection</a>
+    * <a href="https://docs.regulaforensics.com/develop/face-sdk/overview/introduction/#face-comparison-11" target="_blank">Face Match (1:1)</a>
+    * <a href="https://docs.regulaforensics.com/develop/face-sdk/overview/introduction/#face-identification-1n" target="_blank">Face Search (1:N)</a>
+    * <a href="https://docs.regulaforensics.com/develop/face-sdk/overview/introduction/#liveness-assessment" target="_blank">Liveness Assessment</a>
+
+    Here is the <a href="https://github.com/regulaforensics/FaceSDK-web-openapi  " target="_blank">OpenAPI specification on GitHub</a>. 
+
     ### Clients
     * [JavaScript](https://github.com/regulaforensics/FaceSDK-web-js-client) client for the browser and node.js based on axios
     * [Java](https://github.com/regulaforensics/FaceSDK-web-java-client) client compatible with jvm and android

liveness.yml

@@ -31,7 +31,7 @@ components:
           description: "Whether the liveness detection is confirmed (0) or not (1)."
         tag:
           type: string
-          description: "Session identificator."
+          description: "Session identificator, should be unique for each session."
         transactionId:
           type: string
           description: "Transaction ID, there can be several transactions within one session."

match_and_search.yml

@@ -6,7 +6,8 @@ paths:
     post:
       tags:
         - matching
-      summary: 'Match and Search in one request'
+      summary: 'match and search (1:1 + 1:N)'
+      description: "To compare several images from a document and look up a person in the database in one request, use POST `/api/match_and_search`. In this case, the calculation of the descriptor will be performed only once, as opposed to using two requests for the same operation. If only one person is identified, matching is not performed and only search is carried out."
       operationId: match_and_search
       requestBody:
         required: true
@@ -31,10 +32,10 @@ components:
           properties:
             tag:
               type: string
-              description: "Session identificator."
+              description: "Session identificator, should be unique for each session."
             images:
               type: array
-              description: "Array of Person images."
+              description: "Person's images."
               items:
                 type: object
                 properties:
@@ -56,10 +57,12 @@ components:
           properties:
             results:
               type: array
+              description: "The match and search results."
               items:
                 $ref: './matching.yml#/components/schemas/MatchImageResult'
             elapsedTime:
               type: number
+              description: "Time the processing has taken, ms."
               format: float
               example: 1.317137987
             metadata:
@@ -68,11 +71,13 @@ components:
               description: "A free-form object containing person's extended attributes."
             detections:
               type: array
+              description: "The detection results."
               items:
                 type: object
                 properties:
                   faces:
                     type: array
+                    description: "Detected faces."
                     items:
                       $ref: '#/components/schemas/FacesResponse'
                   imageIndex:
@@ -85,6 +90,7 @@ components:
           properties:
             images:
               type: array
+              description: "Detected Persons."
               items:
                 $ref: './search.yml#/definitions/RecognizeImage'
         - $ref: './identification.yml#/components/schemas/Person'
@@ -96,6 +102,7 @@ components:
           properties:
             persons:
               type: array
+              description: "Detected Persons."
               items:
                 $ref: '#/components/schemas/PersonWithImages'
             rotationAngle:

matching.yml

@@ -1,13 +1,25 @@
 openapi: 3.0.3
 paths:
-
   /match:
     parameters:
       - $ref: './common.yml#/components/parameters/x-request'
     post:
       tags:
         - matching
-      summary: "Compare faces in all combinations"
+      summary: "compare faces (1:1)"
+      description: "To perform a comparison of faces in the same image or in two different images, use POST `/api/match`. It's possible to compare faces in the same image or in two different images, this is defined by the `images.type` parameter. <br><br> The face detection result is displayed in the `detections` field.
+
+Each face is identified by two parameters: `faceIndex` (the index number of the face) and `imageIndex` (the index number of the image on which the face is detected).
+
+So, if there are two images each of which has two faces in them, the parameters will be the following:
+
+- First face in the first image: `faceIndex: 0`, `imageIndex: 0`
+
+- Second face in the first image: `faceIndex: 1`, `imageIndex: 0`
+
+- First face of the second image: `faceIndex: 0`, `imageIndex: 1`
+
+- Second face in the second image: `faceIndex: 1`, `imageIndex: 1`"
       operationId: match
       requestBody:
         required: true
@@ -39,15 +51,13 @@ components:
       properties:
         tag:
           type: string
-          description: "Session identificator."
+          description: "Session identificator, should be unique for each session."
         thumbnails:
-          type: boolean
-          description: "Deprecated, use the `crop` field in `outputImageParams` instead."
-          default: false
+          description: "Use `outputImageParams.crop` instead."
           deprecated: true
         images:
           type: array
-          description: "The array of all images included in the comparison."
+          description: "All images included in the comparison."
           items:
             $ref: "#/components/schemas/MatchImage"
         outputImageParams:
@@ -62,7 +72,7 @@ components:
                 type: integer
             crop:
               type: object
-              description: "Whether to return the Base64 of an aligned and cropped portrait in the `crop` field."
+              description: "If set, a Base64-encoded aligned and cropped by the indicated settings portrait is returned in the `crop` field."
               properties:
                 padColor:
                   type: array
@@ -72,7 +82,7 @@ components:
                     type: integer
                 returnOriginalRect:
                   type: boolean
-                  description: "Whether to return the coordinates of the rectangle with the face in the original image prepared for the face crop."
+                  description: "Whether to return the coordinates of the rectangle with the face in the original image prepared for the face crop. Can be used only if the face in the original image is not tilted."
                   default: null
                 size:
                   type: array
@@ -82,7 +92,7 @@ components:
                     type: integer
                 type:
                   type: integer
-                  description: "The aspect ratio according to which face alignment is performed during face detection."
+                  description: "The aspect ratio according to which face alignment is performed. See the [FaceImageQualityAlignType enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-align-type/). To get a thumbnail with dimensions 3x4, set `0`."
                   default: null
                   enum:
                     - 0
@@ -93,7 +103,7 @@ components:
 
     MatchImageIndex:
       type: integer
-      description: "The image index number. Can be given; if not given, the index numbers are set automatically starting from 0. All index numbers must be whole and unique—not repeated."
+      description: "The image index number. Can be given; if not given, the index numbers are set automatically starting from `0`. All index numbers must be whole and unique—not repeated."
 
     MatchFaceIndex:
       type: number
@@ -120,12 +130,12 @@ components:
           properties:
             detections:
               type: array
-              description: "The array of detected faces."
+              description: "The detection results."
               items:
                 $ref: "#/components/schemas/MatchImageDetection"
             results:
               type: array
-              description: "The array of matching results."
+              description: "The comparison results."
               items:
                 $ref: "#/components/schemas/MatchImageResult"
             metadata:
@@ -166,7 +176,7 @@ components:
       properties:
         faces:
           type: array
-          description: "The array of detected faces."
+          description: "Detected faces."
           items:
             $ref: "#/components/schemas/DetectionFace"
         imageIndex:
@@ -199,10 +209,10 @@ components:
         crop:
           type: string
           format: byte
-          description: "Base64 of the cropped portrait."
+          description: "Base64-encoded aligned and cropped portrait."
 
     ImageSource:
-      description: "The type of the image, defines the way the comparison is performed. See the enum: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/image-source/"
+      description: "The type of the image, defines the way the comparison is performed, see the [ImageSource enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/image-source/)."
       type: integer
       enum:
         - 1
@@ -211,15 +221,16 @@ components:
         - 4
         - 5
         - 6
+        - 7
       x-enum-varnames:
         - DOCUMENT_PRINTED
         - DOCUMENT_RFID
         - LIVE
         - DOCUMENT_WITH_LIVE
         - EXTERNAL
         - GHOST
-
+        - BARCODE
     detectAll:
       type: boolean
-      description: "Whether to detect all faces in the image. If set to false, only the most central face is detected."
+      description: "Whether to detect all faces in the image. If set to `false`, only the most central face is detected."
       default: false

search.yml

@@ -105,7 +105,7 @@ definitions:
           format: uuid
       name:
         type: string
-        description: "Person name."
+        description: "Person's name."
         nullable: true
       metadata:
         type: object