diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..bc25558 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Submit a request + url: https://support.regulaforensics.com/hc/requests/new?utm_source=github + about: Submit any requests to Regula Support Team diff --git a/.github/workflows/make-prs-for-client-repos.yml b/.github/workflows/make-prs-for-client-repos.yml index 0e6f2c9..ce35e5d 100644 --- a/.github/workflows/make-prs-for-client-repos.yml +++ b/.github/workflows/make-prs-for-client-repos.yml @@ -30,6 +30,7 @@ jobs: run: gh pr create --base ${{ inputs.target_branch }} --head ${{ inputs.source_branch }} --title '[GitHub Actions] Merge ${{ inputs.source_branch }} -> ${{ inputs.target_branch }}' --label OpenAPI --body 'Autogenerated Pull Request triggered by Github Actions in OpenAPI repository' --repo regulaforensics/FaceSDK-web-python-client env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} + java-webclient-pr: runs-on: ubuntu-latest steps: @@ -37,6 +38,7 @@ jobs: run: gh pr create --base ${{ inputs.target_branch }} --head ${{ inputs.source_branch }} --title '[GitHub Actions] Merge ${{ inputs.source_branch }} -> ${{ inputs.target_branch }}' --label OpenAPI --body 'Autogenerated Pull Request triggered by Github Actions in OpenAPI repository' --repo regulaforensics/FaceSDK-web-java-client env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} + js-webclient-pr: runs-on: ubuntu-latest steps: @@ -44,6 +46,7 @@ jobs: run: gh pr create --base ${{ inputs.target_branch }} --head ${{ inputs.source_branch }} --title '[GitHub Actions] Merge ${{ inputs.source_branch }} -> ${{ inputs.target_branch }}' --label OpenAPI --body 'Autogenerated Pull Request triggered by Github Actions in OpenAPI repository' --repo regulaforensics/FaceSDK-web-js-client env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} + csharp-webclient-pr: runs-on: ubuntu-latest steps: @@ -51,6 +54,7 @@ jobs: run: gh pr create --base ${{ inputs.target_branch }} --head ${{ inputs.source_branch }} --title '[GitHub Actions] Merge ${{ inputs.source_branch }} -> ${{ inputs.target_branch }}' --label OpenAPI --body 'Autogenerated Pull Request triggered by Github Actions in OpenAPI repository' --repo regulaforensics/FaceSDK-web-csharp-client env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} + openapi-pr: runs-on: ubuntu-latest steps: diff --git a/.github/workflows/release-web-page.yml b/.github/workflows/release-web-page.yml index 726e646..6a4a3dc 100644 --- a/.github/workflows/release-web-page.yml +++ b/.github/workflows/release-web-page.yml @@ -10,25 +10,21 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout Specifications - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: path: 'master-branch' - name: Install redoc-cli - uses: actions/setup-node@v1 + uses: actions/setup-node@v4 with: - node-version: 14 + node-version: 20 registry-url: https://registry.npmjs.org/ - name: Build html page working-directory: master-branch run: | - npm install -g redoc-cli; - npx redoc-cli build "./index.yml" --output doc.html \ - --options.maxDisplayedEnumValues=5 --options.theme.logo.gutter="20px" \ - --options.theme.colors.primary.main="#8a53cb" --options.expandResponses="all" \ - --options.expandSingleSchemaField --options.hideDownloadButton \ - --options.jsonSampleExpandLevel="6"; + npm install -g @redocly/cli; + npx @redocly/cli build-docs index.yml -o=doc.html; - name: Checkout pages branch - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: path: 'pages-branch' ref: 'gh-pages' diff --git a/.github/workflows/update-clients.yml b/.github/workflows/update-clients.yml index 0b4b29e..a02da30 100644 --- a/.github/workflows/update-clients.yml +++ b/.github/workflows/update-clients.yml @@ -1,76 +1,131 @@ name: update clients on: - workflow_dispatch: - inputs: - title: - description: "Title for PR's" - required: true + push: + branches: [develop] + workflow_dispatch: + inputs: + title: + description: "Title For PR's" + required: true + branch: + description: "OpenAPI branch" + required: true + default: "develop" jobs: + title: + runs-on: ubuntu-latest + outputs: + title: ${{ steps.get-title.outputs.fmt_title }} + steps: + - id: get-title + run: | + if [[ ${{ github.event_name }} == 'workflow_dispatch' ]]; then + echo "fmt_title=${{ github.event.inputs.title }}" >> "$GITHUB_OUTPUT" + else + echo "fmt_title=${GITHUB_SHA::8}" >> "$GITHUB_OUTPUT" + fi + update-js-client: + needs: title runs-on: ubuntu-latest steps: - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - path: 'FaceSDK-web-openapi' + path: "FaceSDK-web-openapi" + ref: ${{ github.event.inputs.branch }} + - name: Checkout JS Client Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-js-client' + repository: "regulaforensics/FaceSDK-web-js-client" token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'js-client' + path: "js-client" + ref: "develop" + - name: Update Model According To Specification working-directory: js-client run: | npm install ./update-models.sh + - name: Push Changes Back To Client Repo working-directory: js-client run: | git checkout -b ${GITHUB_SHA::8} git config --local user.email "action@github.com" git config --local user.name "GitHub Action" + + if git diff-index --quiet HEAD --; then + echo "No changes to commit." + exit 0 + fi + git add --all - git commit -m "${{ github.event.inputs.title }}" -a - git push --set-upstream origin ${GITHUB_SHA::8} - gh pr create --fill --draft + git commit -m "Commit: ${{ needs.title.outputs.title }}" -a + + if [ $? -eq 0 ]; then + git push --set-upstream origin ${GITHUB_SHA::8} + gh pr create --fill --base develop + else + echo "Nothing to commit." + fi env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} update-java-client: + needs: title runs-on: ubuntu-latest steps: - name: Specify Java Version - uses: actions/setup-java@v1 + uses: actions/setup-java@v4 with: + distribution: "zulu" java-version: 11 java-package: jdk + - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - path: 'FaceSDK-web-openapi' + path: "FaceSDK-web-openapi" + ref: ${{ github.event.inputs.branch }} + - name: Checkout Java Client Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-java-client' + repository: "regulaforensics/FaceSDK-web-java-client" token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'java-client' + path: "java-client" + ref: "develop" + - name: Update Model According To Specification working-directory: java-client run: | ./update-models.sh + - name: Push Changes Back To Client Repo working-directory: java-client run: | git checkout -b ${GITHUB_SHA::8} git config --local user.email "action@github.com" git config --local user.name "GitHub Action" + + if git diff-index --quiet HEAD --; then + echo "No changes to commit." + exit 0 + fi + git add --all - git commit -m "${{ github.event.inputs.title }}" -a - git push --set-upstream origin ${GITHUB_SHA::8} - gh pr create --fill --draft + git commit -m "Commit: ${{ needs.title.outputs.title }}" -a + + if [ $? -eq 0 ]; then + git push --set-upstream origin ${GITHUB_SHA::8} + gh pr create --fill --base develop + else + echo "Nothing to commit." + fi env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} @@ -78,29 +133,45 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - path: 'FaceSDK-web-openapi' + path: "FaceSDK-web-openapi" + ref: ${{ github.event.inputs.branch }} + - name: Checkout Python Client Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-python-client' + repository: "regulaforensics/FaceSDK-web-python-client" token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'python-client' + path: "python-client" + ref: "develop" + - name: Update Model According To Specification working-directory: python-client run: | ./update-models.sh + - name: Push Changes Back To Client Repo working-directory: python-client run: | git checkout -b ${GITHUB_SHA::8} git config --local user.email "action@github.com" git config --local user.name "GitHub Action" + + if git diff-index --quiet HEAD --; then + echo "No changes to commit." + exit 0 + fi + git add --all - git commit -m "${{ github.event.inputs.title }}" -a - git push --set-upstream origin ${GITHUB_SHA::8} - gh pr create --fill --draft + git commit -m "Commit: ${{ needs.title.outputs.title }}" -a + + if [ $? -eq 0 ]; then + git push --set-upstream origin ${GITHUB_SHA::8} + gh pr create --fill --base develop + else + echo "Nothing to commit." + fi env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} @@ -110,31 +181,47 @@ jobs: - name: Specify Dotnet Version uses: actions/setup-dotnet@v1 with: - dotnet-version: '3.1.x' + dotnet-version: "3.1.x" + - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - path: 'FaceSDK-web-openapi' - - name: Checkout CSharp Client Repo - uses: actions/checkout@v2 + path: "FaceSDK-web-openapi" + ref: ${{ github.event.inputs.branch }} + + - name: Checkout C# Client Repo + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-csharp-client' + repository: "regulaforensics/FaceSDK-web-csharp-client" token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'csharp-client' + path: "csharp-client" + ref: "develop" + - name: Update Model According To Specification working-directory: csharp-client run: | ./update-models.sh + - name: Push Changes Back To Client Repo working-directory: csharp-client run: | git checkout -b ${GITHUB_SHA::8} git config --local user.email "action@github.com" git config --local user.name "GitHub Action" - git checkout src/Regula.FaceSDK.WebClient/Api/SearchApi.cs + + if git diff-index --quiet HEAD --; then + echo "No changes to commit." + exit 0 + fi + git add --all - git commit -m "${{ github.event.inputs.title }}" -a - git push --set-upstream origin ${GITHUB_SHA::8} - gh pr create --fill --draft + git commit -m "Commit: ${{ needs.title.outputs.title }}" -a + + if [ $? -eq 0 ]; then + git push --set-upstream origin ${GITHUB_SHA::8} + gh pr create --fill --base develop + else + echo "Nothing to commit." + fi env: GITHUB_TOKEN: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} diff --git a/.github/workflows/validate-spec.yml b/.github/workflows/validate-spec.yml index 6dcc409..b343645 100644 --- a/.github/workflows/validate-spec.yml +++ b/.github/workflows/validate-spec.yml @@ -4,19 +4,29 @@ on: pull_request: branches: - master + - develop + - stable jobs: validate-specification: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v4 + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 with: node-version: 20 registry-url: https://registry.npmjs.org/ - - run: | - npm install -g redoc-cli - npx @redocly/cli build-docs index.yml - - run: | + + - name: Install redoc + run: | + npm install -g @redocly/cli + redocly build-docs index.yml + + - name: Revert changes + if: ${{ false }} + run: | npm install -g @openapitools/openapi-generator-cli - openapi-generator-cli validate -i index.yml + openapi-generator-cli validate --recommend -i index.yml diff --git a/.github/workflows/verify-clients.yml b/.github/workflows/verify-clients.yml index 89f2246..d053cee 100644 --- a/.github/workflows/verify-clients.yml +++ b/.github/workflows/verify-clients.yml @@ -1,92 +1,100 @@ name: verify clients on: - push: - branches: - - master pull_request: branches: - master + - develop + - stable jobs: - verify-js-client: + verify-python: runs-on: ubuntu-latest steps: - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: path: 'FaceSDK-web-openapi' - - name: Checkout JS Client Repo - uses: actions/checkout@v2 + + - name: Checkout Python Client Repo + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-js-client' + repository: 'regulaforensics/FaceSDK-web-python-client' token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'js-client' - - name: Update Model According To Specification - working-directory: js-client + path: 'python-client' + + - name: Verify update Python client + working-directory: python-client run: | - npm install - ./update-models.sh + ./update-models.sh strict + ./setup.sh - verify-java-client: + verify-csharp: runs-on: ubuntu-latest steps: - - name: Specify Java Version - uses: actions/setup-java@v1 - with: - java-version: 11 - java-package: jdk - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: path: 'FaceSDK-web-openapi' - - name: Checkout Java Client Repo - uses: actions/checkout@v2 + + - name: Checkout CSharp Client Repo + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-java-client' + repository: 'regulaforensics/FaceSDK-web-csharp-client' token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'java-client' - - name: Update Model According To Specification - working-directory: java-client + path: 'csharp-client' + + - name: Verify update CSharp client + working-directory: csharp-client run: | - ./update-models.sh + ./update-models.sh strict + ./setup.sh - verify-python-client: + verify-js: runs-on: ubuntu-latest steps: - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - path: 'FaceSDK-web-openapi' - - name: Checkout Python Client Repo - uses: actions/checkout@v2 + path: "FaceSDK-web-openapi" + + - name: Checkout JS Client Repo + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-python-client' + repository: "regulaforensics/FaceSDK-web-js-client" token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'python-client' - - name: Update Model According To Specification - working-directory: python-client + path: "js-client" + + - name: Verify update JS client + working-directory: js-client run: | ./update-models.sh + ./setup.sh - verify-csharp-client: + verify-java: runs-on: ubuntu-latest steps: - - name: Specify Dotnet Version - uses: actions/setup-dotnet@v1 + - name: Specify Java Version + uses: actions/setup-java@v4 with: - dotnet-version: '3.1.x' + distribution: "zulu" + java-version: 11 + java-package: jdk + - name: Checkout Specification Repo - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: path: 'FaceSDK-web-openapi' - - name: Checkout CSharp Client Repo - uses: actions/checkout@v2 + + - name: Checkout Java Client Repo + uses: actions/checkout@v4 with: - repository: 'regulaforensics/FaceSDK-web-csharp-client' + repository: 'regulaforensics/FaceSDK-web-java-client' token: ${{ secrets.REGULA_GITHUB_PUSH_TOKEN }} - path: 'csharp-client' - - name: Update Model According To Specification - working-directory: csharp-client + path: 'java-client' + + - name: Verify update Java client + working-directory: java-client run: | - ./update-models.sh \ No newline at end of file + ./update-models.sh strict + ./gradlew clean :example:run diff --git a/.gitignore b/.gitignore index a969940..83e400a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .idea +*.DS_Store *.html /sample.json diff --git a/README.md b/README.md index e3c57eb..24011bb 100644 --- a/README.md +++ b/README.md @@ -11,22 +11,28 @@ * [Python](https://github.com/regulaforensics/FaceSDK-web-python-client) 3.5+ client * [C#](https://github.com/regulaforensics/FaceSDK-web-csharp-client) client for .NET & .NET Core +## Updating clients according to the current spec -## Generate html page -```bash -npx redoc-cli build "$PWD/index.yml" --output facesdk-api-doc.html \ ---options.maxDisplayedEnumValues=5 --options.theme.logo.gutter="20px" \ ---options.theme.colors.primary.main="#8a53cb" --options.expandResponses="all" \ ---options.expandSingleSchemaField --options.hideDownloadButton --options.jsonSampleExpandLevel="6" -``` +When changes are added, the `update clients` action is automatically triggered. For each client **PR** with changes will be created. +:warning: NOTE: Before working with a client, read `dev.md` which is available in each client repository. -## Updating clients according to the current spec +:warning: NOTE: Do **not edit** generated code. Create wrappers, decorators, etc. in ext folder. + +## Spec validation + +```bash +docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli validate --recommend -i /local/index.yml +``` -To update clients, use `update clients` GitHub action. Specify title PR and press run. For each client **PR** with changes will be created. +## Building Redoc single page html documentation -:warning: NOTE: Static typed clients, such as Java or C#, require adding all new **enums** to `update-models.sh` ENUM_MAPPINGS section. +```bash +npx @redocly/cli build-docs index.yml -o=facesdk-api-doc.html +``` -:warning: NOTE: For some clients generator produces not-valid client code. See `update-models.sh` for ad-hocks fixing generator issues. +## Bundle scheme to single .json file -:warning: NOTE: Do **not edit** generated code. Create wrappers, decorators, etc in ext folder. +```bash +npx @openapitools/openapi-generator-cli generate -i index.yml -g openapi --skip-validate-spec +``` diff --git a/common.yml b/common.yml index a849037..990b8f1 100644 --- a/common.yml +++ b/common.yml @@ -1,4 +1,4 @@ -openapi: 3.0.3 +openapi: 3.0.4 components: parameters: @@ -50,6 +50,7 @@ components: schemas: ProcessParam: + title: "ProcessParam" type: object description: "The processing parameters." properties: @@ -71,36 +72,34 @@ components: $ref: "./common.yml#/components/schemas/AttributeConfigList" OutputImageParams: + title: "OutputImageParams" type: object description: "Allows to process the uploaded image according to the indicated settings." properties: backgroundColor: - description: "The RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color." $ref: "#/components/schemas/RGB" crop: $ref: "#/components/schemas/Crop" QualityRequest: + title: "QualityRequest" type: object description: "If set, the face image quality check is performed according to the given list of [characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/) in `quality.config`." properties: backgroundMatchColor: - description: "The RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color." $ref: "#/components/schemas/RGB" config: $ref: "#/components/schemas/QualityConfigList" Crop: + title: "Crop" type: object description: "Whether to return a Base64-encoded image of each aligned and cropped portrait in the `crop` field. Faces are aligned to a straight vertical line based on the value in the `crop.type` field, correcting any tilt present in the original image. If the image contains multiple faces, the system will detect and process each face separately, returning individual portraits. For example, if there are five people in the photo, five processed portraits will be returned. Each portrait is available for download." properties: type: $ref: "#/components/schemas/FaceImageQualityAlignType" - 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`." - example: 1 padColor: $ref: "#/components/schemas/RGB" - description: "The RGB value of a color for filling background behind a person's silhouette and for aligning the image." size: type: array items: @@ -111,19 +110,19 @@ components: example: [300, 400] QualityConfigList: + title: "QualityConfigList" type: array description: "The list of quality check characteristics." items: $ref: "#/components/schemas/QualityConfig" QualityConfig: + title: "QualityConfig" type: object description: "The configuration that defines the list of returned quality check characteristics." properties: name: - description: "The name of the characteristic." $ref: "#/components/schemas/FaceQualityConfigName" - example: "Emotion" range: type: array items: @@ -135,29 +134,28 @@ components: example: [x, y] AttributeConfigList: + title: "AttributeConfigList" type: array description: "The list of attributes for evaluation." items: $ref: "#/components/schemas/AttributeConfig" AttributeConfig: + title: "AttributeConfig" type: object description: "The configuration that defines the list of returned attribute check characteristics." properties: name: - description: "The name of the characteristic." $ref: "#/components/schemas/FaceAttribute" - example: "Emotion" QualityDetailsGroups: + title: "QualityDetailsGroups" type: object properties: groupId: - description: "The ID of the characteristics group." $ref: "#/components/schemas/FaceImageQualityGroups" name: $ref: "#/components/schemas/FaceImageQualityGroupsStrings" - description: "The name of the characteristics group." totalCount: type: integer description: "The total number of characteristics in the group." @@ -168,16 +166,13 @@ components: example: 4 QualityDetail: + title: "QualityDetail" type: object properties: groupId: - description: "The ID of the characteristics group." $ref: "#/components/schemas/FaceImageQualityGroups" - example: 0 name: $ref: "#/components/schemas/FaceQualityConfigName" - description: "The name of the characteristic." - example: "Roll" range: type: array description: "The range of set values for this characteristic, see the [Recommended range column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/)." @@ -189,8 +184,6 @@ components: example: [x, y] status: $ref: "#/components/schemas/FaceImageQualityStatus" - example: 1 - description: "The assessment status." value: type: number format: float @@ -198,6 +191,7 @@ components: example: 0.0 RGB: + title: "RGB" type: array description: "The RGB value of a color for filling background behind a person's silhouette and for aligning the image." items: @@ -207,6 +201,7 @@ components: example: [128, 128, 128] FaceImageQualityStatus: + title: "FaceImageQualityStatus" type: integer description: "The processing status returned for each quality characteristic, see the [FaceImageQualityStatus enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-status/)." enum: @@ -214,11 +209,12 @@ components: - 1 - 2 x-enum-varnames: - - QUALITY_STATUS_FALSE - - QUALITY_STATUS_TRUE - - QUALITY_STATUS_UNDETERMINED + - "QUALITY_STATUS_FALSE" + - "QUALITY_STATUS_TRUE" + - "QUALITY_STATUS_UNDETERMINED" FaceQualityScenarios: + title: "FaceQualityScenarios" type: string description: "Face detection scenario. If set and the scenario is found, it automatically applies the relevant parameters, overriding any other parameters specified in the request. If the scenario is not set, is empty, or the name is not recognized, processing will follow the parameters directly set in the request. For detailed descriptions of available scenarios, refer to the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)." example: "QualityICAO" @@ -234,18 +230,19 @@ components: - "AttributesAll" - "" x-enum-varnames: - - OLD_MODE - - QUALITY_FULL - - QUALITY_ICAO - - QUALITY_VISA_SCHENGEN - - QUALITY_VISA_USA - - CROP_CENTRAL_FACE - - CROP_ALL_FACES - - THUMBNAIL - - ATTRIBUTES_ALL - - EMPTY + - "OLD_MODE" + - "QUALITY_FULL" + - "QUALITY_ICAO" + - "QUALITY_VISA_SCHENGEN" + - "QUALITY_VISA_USA" + - "CROP_CENTRAL_FACE" + - "CROP_ALL_FACES" + - "THUMBNAIL" + - "ATTRIBUTES_ALL" + - "EMPTY" FaceImageQualityGroups: + title: "FaceImageQualityGroups" type: integer description: "The group ID of the characteristic, see the [FaceImageQualityGroups enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/) for details." enum: @@ -258,15 +255,17 @@ components: - 7 - 8 x-enum-varnames: - - IMAGE_CHARACTERISTICS - - HEAD_SIZE_AND_POSITIONS - - FACE_QUALITY - - EYES_CHARACTERISTICS - - SHADOWS_AND_LIGHTNING - - POSE_AND_EXPRESSION - - HEAD_OCCLUSION - - BACKGROUND + - "IMAGE_CHARACTERISTICS" + - "HEAD_SIZE_AND_POSITIONS" + - "FACE_QUALITY" + - "EYES_CHARACTERISTICS" + - "SHADOWS_AND_LIGHTNING" + - "POSE_AND_EXPRESSION" + - "HEAD_OCCLUSION" + - "BACKGROUND" + FaceImageQualityGroupsStrings: + title: "FaceImageQualityGroupsStrings" type: string description: "Face image quality assessment group name, see [FaceImageQualityGroups](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/)." enum: @@ -279,16 +278,17 @@ components: - "HeadOcclusion" - "Background" x-enum-varnames: - - IMAGE_CHARACTERISTICS - - HEAD_SIZE_AND_POSITIONS - - FACE_QUALITY - - EYES_CHARACTERISTICS - - SHADOWS_AND_LIGHTNING - - POSE_AND_EXPRESSION - - HEAD_OCCLUSION - - BACKGROUND + - "IMAGE_CHARACTERISTICS" + - "HEAD_SIZE_AND_POSITIONS" + - "FACE_QUALITY" + - "EYES_CHARACTERISTICS" + - "SHADOWS_AND_LIGHTNING" + - "POSE_AND_EXPRESSION" + - "HEAD_OCCLUSION" + - "BACKGROUND" FaceQualityConfigName: + title: "FaceQualityConfigName" type: string description: "The name of the characteristic. For definitions, see the [FaceQualityConfigName enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-quality-config-name/)." enum: @@ -341,56 +341,57 @@ components: - "ArtFace" - "ContactLenses" x-enum-varnames: - - IMAGE_WIDTH - - IMAGE_HEIGHT - - IMAGE_WIDTH_TO_HEIGHT - - IMAGE_CHANNELS_NUMBER - - PADDING_RATIO - - FACE_MID_POINT_HORIZONTAL_POSITION - - FACE_MID_POINT_VERTICAL_POSITION - - HEAD_WIDTH_RATIO - - HEAD_HEIGHT_RATIO - - EYES_DISTANCE - - YAW - - PITCH - - ROLL - - BLUR_LEVEL - - NOISE_LEVEL - - EYE_RIGHT_CLOSED - - EYE_LEFT_CLOSED - - EYE_RIGHT_OCCLUDED - - EYE_LEFT_OCCLUDED - - EYES_RED - - EYE_RIGHT_COVERED_WITH_HAIR - - EYE_LEFT_COVERED_WITH_HAIR - - OFF_GAZE - - FACE_DYNAMIC_RANGE - - UNNATURAL_SKIN_TONE - - TOO_DARK - - TOO_LIGHT - - FACE_GLARE - - SHADOWS_ON_FACE - - DARK_GLASSES - - REFLECTION_ON_GLASSES - - FRAMES_TOO_HEAVY - - FACE_OCCLUDED - - HEAD_COVERING - - BACKGROUND_UNIFORMITY - - SHADOWS_ON_BACKGROUND - - OTHER_FACES - - SHOULDERS_POSE - - EXPRESSION_LEVEL - - MOUTH_OPEN - - FOREHEAD_COVERING - - SMILE - - STRONG_MAKEUP - - HEADPHONES - - MEDICAL_MASK - - BACKGROUND_COLOR_MATCH - - ART_FACE - - CONTACT_LENSES + - "IMAGE_WIDTH" + - "IMAGE_HEIGHT" + - "IMAGE_WIDTH_TO_HEIGHT" + - "IMAGE_CHANNELS_NUMBER" + - "PADDING_RATIO" + - "FACE_MID_POINT_HORIZONTAL_POSITION" + - "FACE_MID_POINT_VERTICAL_POSITION" + - "HEAD_WIDTH_RATIO" + - "HEAD_HEIGHT_RATIO" + - "EYES_DISTANCE" + - "YAW" + - "PITCH" + - "ROLL" + - "BLUR_LEVEL" + - "NOISE_LEVEL" + - "EYE_RIGHT_CLOSED" + - "EYE_LEFT_CLOSED" + - "EYE_RIGHT_OCCLUDED" + - "EYE_LEFT_OCCLUDED" + - "EYES_RED" + - "EYE_RIGHT_COVERED_WITH_HAIR" + - "EYE_LEFT_COVERED_WITH_HAIR" + - "OFF_GAZE" + - "FACE_DYNAMIC_RANGE" + - "UNNATURAL_SKIN_TONE" + - "TOO_DARK" + - "TOO_LIGHT" + - "FACE_GLARE" + - "SHADOWS_ON_FACE" + - "DARK_GLASSES" + - "REFLECTION_ON_GLASSES" + - "FRAMES_TOO_HEAVY" + - "FACE_OCCLUDED" + - "HEAD_COVERING" + - "BACKGROUND_UNIFORMITY" + - "SHADOWS_ON_BACKGROUND" + - "OTHER_FACES" + - "SHOULDERS_POSE" + - "EXPRESSION_LEVEL" + - "MOUTH_OPEN" + - "FOREHEAD_COVERING" + - "SMILE" + - "STRONG_MAKEUP" + - "HEADPHONES" + - "MEDICAL_MASK" + - "BACKGROUND_COLOR_MATCH" + - "ART_FACE" + - "CONTACT_LENSES" FaceSDKResult: + title: "FaceSDKResult" type: object required: - code @@ -399,11 +400,13 @@ components: $ref: "#/components/schemas/FaceSDKResultCode" ImageData: + title: "ImageData" description: "Base64-encoded image." type: string format: byte OperationLog: + title: "OperationLog" type: object properties: statusCode: @@ -419,7 +422,9 @@ components: type: object additionalProperties: true description: "A free-form object containing group's extended attributes." + Page: + title: "Page" type: object description: "Information about current page number and total pages count" properties: @@ -433,10 +438,12 @@ components: example: 2 Bytes: + title: "Bytes" type: string format: binary FaceImageQualityAlignType: + title: "FaceImageQualityAlignType" type: integer 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 aspect ratio 3:4, set `0`." enum: @@ -446,13 +453,14 @@ components: - 3 - 4 x-enum-varnames: - - ALIGN_3x4 - - ALIGN_4x5 - - ALIGN_2x3 - - ALIGN_1x1 - - ALIGN_7x9 + - "ALIGN_3x4" + - "ALIGN_4x5" + - "ALIGN_2x3" + - "ALIGN_1x1" + - "ALIGN_7x9" FaceSDKResultCode: + title: "FaceSDKResultCode" type: integer description: "The result code, see the [FaceSDKResultCode enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/)." enum: @@ -498,55 +506,57 @@ components: - 253 - 254 x-enum-varnames: - - FACER_OK - - FR_IMAGE_EMPTY - - FR_FACE_NOT_DETECTED - - FR_LANDMARKS_NOT_DETECTED - - FR_FACE_ALIGHNER_FAILED - - FR_DESCRIPTOR_EXTRACTOR_ERROR - - FR_IMAGE_DECODE_ERROR - - FR_INTERNAL_ERROR - - FACER_CONFIG_ERROR - - FACER_NO_LICENSE - - FACER_IS_NOT_INITIALIZED - - FACER_COMMAND_IS_NOT_SUPPORTED - - FACER_COMMAND_PARAMS_READ_ERROR - - FACER_LESS_THAN_TWO_IMAGES_IN_REQUEST - - FACER_VIDEO_DECODE_ERROR - - FACER_NOT_ENOUGH_FRAMES - - FACER_OUTPUT_IS_NOT_DEFINED - - FACER_CLOSED_EYES_DETECTED - - FACER_LOW_QUALITY - - FACER_HIGH_ASYMMETRY - - FACER_FACE_OVER_EMOTIONAL - - FACER_SUNGLASSES_DETECTED - - FACER_SMALL_AGE - - FACER_HEADDRESS_DETECTED - - FACER_FACES_NOT_MATCHED - - FACER_IMAGES_COUNT_LIMIT_EXCEEDED - - FACER_MEDICINE_MASK_DETECTED - - FACER_OCCLUSION_DETECTED - - FACER_FOREHEAD_GLASSES_DETECTED - - FACER_MOUTH_OPENED - - FACER_ART_MASK_DETECTED - - FACER_ELECTRONIC_DEVICE_DETECTED - - FACER_TRACK_BREAK - - FACER_WRONG_GEO - - FACER_WRONG_OF - - FACER_WRONG_VIEW - - FACER_TIMEOUT_LIVENESS_TRANSACTION - - FACER_FAILED_LIVENESS_TRANSACTION - - FACER_ABORTED_LIVENESS_TRANSACTION - - FACER_GENERAL_ERROR - - FACER_PASSIVE_LIVENESS_FAIL + - "FACER_OK" + - "FR_IMAGE_EMPTY" + - "FR_FACE_NOT_DETECTED" + - "FR_LANDMARKS_NOT_DETECTED" + - "FR_FACE_ALIGHNER_FAILED" + - "FR_DESCRIPTOR_EXTRACTOR_ERROR" + - "FR_IMAGE_DECODE_ERROR" + - "FR_INTERNAL_ERROR" + - "FACER_CONFIG_ERROR" + - "FACER_NO_LICENSE" + - "FACER_IS_NOT_INITIALIZED" + - "FACER_COMMAND_IS_NOT_SUPPORTED" + - "FACER_COMMAND_PARAMS_READ_ERROR" + - "FACER_LESS_THAN_TWO_IMAGES_IN_REQUEST" + - "FACER_VIDEO_DECODE_ERROR" + - "FACER_NOT_ENOUGH_FRAMES" + - "FACER_OUTPUT_IS_NOT_DEFINED" + - "FACER_CLOSED_EYES_DETECTED" + - "FACER_LOW_QUALITY" + - "FACER_HIGH_ASYMMETRY" + - "FACER_FACE_OVER_EMOTIONAL" + - "FACER_SUNGLASSES_DETECTED" + - "FACER_SMALL_AGE" + - "FACER_HEADDRESS_DETECTED" + - "FACER_FACES_NOT_MATCHED" + - "FACER_IMAGES_COUNT_LIMIT_EXCEEDED" + - "FACER_MEDICINE_MASK_DETECTED" + - "FACER_OCCLUSION_DETECTED" + - "FACER_FOREHEAD_GLASSES_DETECTED" + - "FACER_MOUTH_OPENED" + - "FACER_ART_MASK_DETECTED" + - "FACER_ELECTRONIC_DEVICE_DETECTED" + - "FACER_TRACK_BREAK" + - "FACER_WRONG_GEO" + - "FACER_WRONG_OF" + - "FACER_WRONG_VIEW" + - "FACER_TIMEOUT_LIVENESS_TRANSACTION" + - "FACER_FAILED_LIVENESS_TRANSACTION" + - "FACER_ABORTED_LIVENESS_TRANSACTION" + - "FACER_GENERAL_ERROR" + - "FACER_PASSIVE_LIVENESS_FAIL" Thumbnail: + title: "Thumbnail" description: "See `crop` instead." deprecated: true type: string format: byte FaceRectangular: + title: "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." type: array items: @@ -554,6 +564,7 @@ components: example: [x, y, width, height] FaceAttribute: + title: "FaceAttribute" type: string description: "The name of the attribute. For definitions, see the [FaceAttribute enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-attribute/)." enum: @@ -571,21 +582,22 @@ components: - "StrongMakeup" - "Headphones" x-enum-varnames: - - AGE - - EMOTION - - EYE_LEFT - - EYE_RIGHT - - SMILE - - GLASSES - - HEAD_COVERING - - FOREHEAD_COVERING - - MOUTH - - MEDICAL_MASK - - OCCLUSION - - STRONG_MAKEUP - - HEADPHONES + - "AGE" + - "EMOTION" + - "EYE_LEFT" + - "EYE_RIGHT" + - "SMILE" + - "GLASSES" + - "HEAD_COVERING" + - "FOREHEAD_COVERING" + - "MOUTH" + - "MEDICAL_MASK" + - "OCCLUSION" + - "STRONG_MAKEUP" + - "HEADPHONES" ImageSource: + title: "ImageSource" type: integer description: "Face photo image source types: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/image-source/" enum: @@ -595,15 +607,18 @@ components: - 4 - 5 - 6 + - 7 x-enum-varnames: - - DOCUMENT_PRINTED - - DOCUMENT_RFID - - LIVE - - DOCUMENT_WITH_LIVE - - EXTERNAL - - GHOST + - "DOCUMENT_PRINTED" + - "DOCUMENT_RFID" + - "LIVE" + - "DOCUMENT_WITH_LIVE" + - "EXTERNAL" + - "GHOST" + - "BARCODE" FaceLivenessStatus: + title: "FaceLivenessStatus" type: integer description: "The liveness assessment status: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-liveness-status/" enum: @@ -611,6 +626,17 @@ components: - 1 - 2 x-enum-varnames: - - LVC_REAL - - LVC_FAKE - - LVC_UNKNOWN + - "LVC_REAL" + - "LVC_FAKE" + - "LVC_UNKNOWN" + + TransactionLabels: + title: "TransactionLabels" + type: object + properties: + tenant: + type: string + description: "A label used to group transactions by customers, applications, or other criteria." + env: + type: string + description: "A label used to differentiate transactions by development stages." diff --git a/detect.yml b/detect.yml index d58dcec..03dd420 100644 --- a/detect.yml +++ b/detect.yml @@ -1,8 +1,9 @@ -openapi: 3.0.3 +openapi: 3.0.4 + paths: /detect: parameters: - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" post: tags: - match @@ -21,7 +22,7 @@ paths: - By adding parameters manually. In this case, the configuration is not saved and you will need to add all the necessary parameters to each request. - - By a processing `scenario` that includes certain parameters. You can use predefined scenarios or add custom ones. For detailed information about scenarios, refer to the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)." + - By a processing `scenario` that includes certain parameters. You can use predefined scenarios or add custom ones. For detailed information about scenarios, refer to the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)." operationId: detect requestBody: required: true @@ -42,6 +43,14 @@ paths: components: schemas: DetectRequest: + title: "DetectRequest" + type: object + allOf: + - $ref: "./common.yml#/components/schemas/TransactionLabels" + - $ref: "#/components/schemas/DetectRequestData" + + DetectRequestData: + title: "DetectRequestData" type: object properties: tag: @@ -51,22 +60,22 @@ components: $ref: "./common.yml#/components/schemas/ProcessParam" image: $ref: "./common.yml#/components/schemas/ImageData" - tenant: - type: string - description: "A label used to group transactions by customers, applications, or other criteria." - env: - type: string - description: "A label used to differentiate transactions by development stages." DetectResponse: + title: "DetectResponse" allOf: - - $ref: './common.yml#/components/schemas/FaceSDKResult' - - type: object - properties: - results: - $ref: '#/components/schemas/DetectResult' + - $ref: "./common.yml#/components/schemas/FaceSDKResult" + - $ref: "#/components/schemas/DetectResponseResults" + + DetectResponseResults: + title: "DetectResponseResults" + type: object + properties: + results: + $ref: "#/components/schemas/DetectResult" DetectResult: + title: "DetectResult" type: object description: "The detection results." required: @@ -93,11 +102,15 @@ components: example: 0.84793560000000001 DetectAttributesDetails: + title: "DetectAttributesDetails" + allOf: + - $ref: "#/components/schemas/DetailItem" + - $ref: "#/components/schemas/AttributesData" + + AttributesData: + title: "AttributesData" type: object properties: - name: - type: string - description: "The name of the attribute." value: type: array description: "The estimated value for the attribute, see the [Returned values column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/)." @@ -105,6 +118,14 @@ components: type: integer DetectDetailsMeta: + title: "DetectDetailsMeta" + allOf: + - $ref: "#/components/schemas/DetailItem" + - $ref: "#/components/schemas/DetectMetaData" + + + DetectMetaData: + title: "DetectMetaData" type: object properties: confidence: @@ -114,32 +135,18 @@ components: value: type: string description: "The estimated value for the attribute, see the [Returned values column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/)." - name: - type: string - description: "The name of the attribute." + Detection: + title: "Detection" type: object required: - landmarks - roi properties: crop: - description: "Base64 of the aligned and cropped portrait. Returned if align is set." $ref: "./common.yml#/components/schemas/ImageData" attributes: - type: object - description: "The evaluated attributes, see the [Attributes List](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/) for details." - properties: - details: - type: array - description: "Attributes assessment details. Returns `DetectDetailsMeta` or `DetectAttributesDetails`." - items: - anyOf: - - $ref: '#/components/schemas/DetectAttributesDetails' - - $ref: '#/components/schemas/DetectDetailsMeta' - elapsedTime: - type: number - description: "Server processing time for attribute detection, ms." + $ref: "#/components/schemas/DetectionAttributes" landmarks: description: "Absolute coordinates (X,Y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips." type: array @@ -151,68 +158,79 @@ components: example: [ x, y ] example: [ [ x, y ] ] quality: - type: object - description: "The portrait quality assessment results, see [Face Image Quality Characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/). If not set in request, no quality check is performed." - properties: - nonCompliant: - type: array - description: "Non-compliant assessment characteristics." - items: - $ref: "./common.yml#/components/schemas/FaceQualityConfigName" - example: ["ImageWidthToHeight", "Yaw"] - detailsGroups: - description: "Assessment results for each [group of characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/)." - type: array - items: - $ref: "./common.yml#/components/schemas/QualityDetailsGroups" - details: - type: array - description: "Assessment characteristics that were set in the request." - items: - $ref: "./common.yml#/components/schemas/QualityDetail" - - score: - type: number - format: float - description: "Returns the estimated portrait quality assessment result, - a number from `0` to `1`, where `1` is for absolute compliance." - example: -1.0 - elapsedTime: - type: number - format: float - description: "Server processing time for quality assessment, ms." - example: 0.42036411166191101 + $ref: "#/components/schemas/DetectionQuality" roi: $ref: "./common.yml#/components/schemas/FaceRectangular" - FaceAttribute: - description: "Face attributes for evaluation." - type: string - enum: - - Age - - Emotion - - EyeLeft - - EyeRight - - Smile - - Glasses - - HeadCovering - - ForeheadCovering - - Mouth - - MedicalMask - - Occlusion - - StrongMakeup - - Headphones - x-enum-varnames: - - AGE - - EMOTION - - EYE_LEFT - - EYE_RIGHT - - SMILE - - GLASSES - - HEAD_COVERING - - FOREHEAD_COVERING - - MOUTH - - MEDICAL_MASK - - OCCLUSION - - STRONG_MAKEUP - - HEADPHONES + DetectionAttributes: + title: "DetectionAttributes" + type: object + description: "The evaluated attributes, see the [Attributes List](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/) for details." + properties: + details: + type: array + description: "Attributes assessment details. Returns `DetectDetailsMeta` or `DetectAttributesDetails`." + items: + oneOf: + - $ref: "#/components/schemas/DetectAttributesDetails" + - $ref: "#/components/schemas/DetectDetailsMeta" + elapsedTime: + type: number + description: "Server processing time for attribute detection, ms." + + DetailItem: + title: "DetailItem" + type: object + properties: + name: + description: "The name of the attribute." + type: string + discriminator: + propertyName: name + mapping: + Age: "DetectAttributesDetails" + EyeRight: "DetectDetailsMeta" + EyeLeft: "DetectDetailsMeta" + Emotion: "DetectDetailsMeta" + Smile: "DetectDetailsMeta" + Glasses: "DetectDetailsMeta" + HeadCovering: "DetectDetailsMeta" + ForeheadCovering: "DetectDetailsMeta" + Mouth: "DetectDetailsMeta" + MedicalMask: "DetectDetailsMeta" + Occlusion: "DetectDetailsMeta" + StrongMakeup: "DetectDetailsMeta" + Headphones: "DetectDetailsMeta" + + DetectionQuality: + title: "DetectionQuality" + type: object + description: "The portrait quality assessment results, see [Face Image Quality Characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/). If not set in request, no quality check is performed." + properties: + nonCompliant: + type: array + description: "Non-compliant assessment characteristics." + items: + $ref: "./common.yml#/components/schemas/FaceQualityConfigName" + example: [ "ImageWidthToHeight", "Yaw" ] + detailsGroups: + description: "Assessment results for each [group of characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/)." + type: array + items: + $ref: "./common.yml#/components/schemas/QualityDetailsGroups" + details: + type: array + description: "Assessment characteristics that were set in the request." + items: + $ref: "./common.yml#/components/schemas/QualityDetail" + score: + type: number + format: float + description: "Returns the estimated portrait quality assessment result, + a number from `0` to `1`, where `1` is for absolute compliance." + example: -1.0 + elapsedTime: + type: number + format: float + description: "Server processing time for quality assessment, ms." + example: 0.42036411166191101 diff --git a/groups.yml b/groups.yml index 1b349a1..a27768b 100644 --- a/groups.yml +++ b/groups.yml @@ -1,18 +1,17 @@ -openapi: 3.0.3 - +openapi: 3.0.4 paths: /groups: parameters: - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - group summary: Get groups operationId: get_all_groups parameters: - - $ref: './common.yml#/components/parameters/page' - - $ref: './common.yml#/components/parameters/size' + - $ref: "./common.yml#/components/parameters/page" + - $ref: "./common.yml#/components/parameters/size" responses: 200: description: "Successful operation, return all groups." @@ -39,10 +38,11 @@ paths: $ref: "#/components/responses/SuccessGroup" 400: $ref: "./common.yml#/components/responses/BadRequest" + /groups/{groupId}: parameters: - - $ref: '#/components/parameters/groupId' - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "#/components/parameters/groupId" + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - group @@ -84,28 +84,29 @@ paths: $ref: "#/components/responses/SuccessEmpty" 404: $ref: "#/components/responses/GroupNotFound" + /groups/{groupId}/persons: parameters: - $ref: "#/components/parameters/groupId" - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - group summary: Get group persons operationId: get_all_persons_by_group_id parameters: - - $ref: './common.yml#/components/parameters/page' - - $ref: './common.yml#/components/parameters/size' + - $ref: "./common.yml#/components/parameters/page" + - $ref: "./common.yml#/components/parameters/size" responses: - '200': + "200": description: "Successful operation, return all persons." content: application/json: schema: $ref: "./identification.yml#/components/schemas/PersonsPage" - '400': + "400": $ref: "./common.yml#/components/responses/BadRequest" - '404': + "404": description: "Group with the groupId or persons with the personIds are not found." content: application/json: @@ -122,7 +123,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/UpdateGroup" + $ref: "#/components/schemas/UpdateGroup" responses: 204: $ref: "#/components/responses/SuccessEmpty" @@ -141,6 +142,7 @@ components: schema: type: string format: uuid + responses: SuccessEmpty: description: "Successful operation, return nothing." @@ -157,20 +159,21 @@ components: schema: $ref: "./common.yml#/components/schemas/OperationLog" -definitions: - UpdateGroup: - type: object - description: "Update group." - properties: - addItems: - type: array - description: "Add items." - items: - type: string - format: uuid - removeItems: - type: array - description: "Remove items." - items: - type: string - format: uuid \ No newline at end of file + schemas: + UpdateGroup: + title: "UpdateGroup" + type: object + description: "Update group." + properties: + addItems: + type: array + description: "Add items." + items: + type: string + format: uuid + removeItems: + type: array + description: "Remove items." + items: + type: string + format: uuid diff --git a/healthcheck.yml b/healthcheck.yml index e82ffa0..9c5f295 100644 --- a/healthcheck.yml +++ b/healthcheck.yml @@ -1,4 +1,4 @@ -openapi: 3.0.3 +openapi: 3.0.4 paths: /healthz: @@ -17,6 +17,7 @@ paths: application/json: schema: $ref: "#/components/schemas/DeviceInfo" + /readyz: parameters: - $ref: "./common.yml#/components/parameters/x-request" @@ -35,8 +36,14 @@ paths: components: schemas: DeviceInfo: + title: "DeviceInfo" type: object - required: [app, licenseId, licenseSerial, licenseValidUntil, version] + required: + - app + - licenseId + - licenseSerial + - licenseValidUntil + - version properties: app: description: Application name. diff --git a/identification.yml b/identification.yml index f3f5029..bc40a19 100644 --- a/identification.yml +++ b/identification.yml @@ -1,4 +1,4 @@ -openapi: 3.0.3 +openapi: 3.0.4 components: responses: @@ -8,8 +8,10 @@ components: application/json: schema: $ref: "#/components/schemas/SearchBadParams" + schemas: SearchBadParams: + title: "SearchBadParams" type: object properties: msg: @@ -21,38 +23,46 @@ components: type: type: string default: "BadParamsException" + PersonsPage: + title: "PersonsPage" allOf: - - type: object - properties: - items: - type: array - items: - $ref: "#/components/schemas/Person" - - $ref: './common.yml#/components/schemas/Page' + - $ref: "#/components/schemas/PersonItems" + - $ref: "./common.yml#/components/schemas/Page" + + PersonItems: + title: "PersonItems" + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/Person" + Person: + title: "Person" description: "Person response body: person ID, creation date, update date if any." allOf: - - $ref: '#/components/schemas/PersonFields' - - type: object - properties: - id: - type: string - format: uuid - description: "Person ID. The list of persons is sorted by decreasing ID value." - createdAt: - type: string - description: "Person creation date." - updatedAt: - type: string - description: "Person update date." - groups: - type: array - description: "List of groups this person belongs to." - items: - type: string - format: uuid + - $ref: "#/components/schemas/PersonFields" + - $ref: "#/components/schemas/PersonData" + + PersonData: + title: "PersonData" + type: object + properties: + id: + type: string + format: uuid + description: "Person ID. The list of persons is sorted by decreasing ID value." + createdAt: + type: string + description: "Person creation date." + updatedAt: + type: string + description: "Person update date." + PersonFields: + title: "PersonFields" type: object description: "Person Request body: name and metadata." required: @@ -77,7 +87,9 @@ components: expireAt: type: string description: "Person expiration date." + PersonToUpdateFields: + title: "PersonToUpdateFields" type: object description: "Person Request body: name and metadata." properties: @@ -99,6 +111,7 @@ components: format: uuid ImageFields: + title: "ImageFields" type: object description: "Image in the request data, includes image and contentType." properties: @@ -106,19 +119,7 @@ components: type: string description: "Session identificator, should be unique for each session." image: - type: object - description: "Uploaded image." - properties: - contentType: - type: string - description: "Original media type of the uploaded image." - content: - $ref: "./common.yml#/components/schemas/ImageData" - imageUrl: - type: string - description: "Image URL." - resizeOptions: - $ref: "#/components/schemas/ResizeOptions" + $ref: "#/components/schemas/ImageFieldsImage" outputImageParams: $ref: "./common.yml#/components/schemas/OutputImageParams" detectAll: @@ -131,7 +132,24 @@ components: type: integer description: "The maximum number of results to be returned." + ImageFieldsImage: + title: "ImageFieldsImage" + type: object + description: "Uploaded image." + properties: + contentType: + type: string + description: "Original media type of the uploaded image." + content: + $ref: "./common.yml#/components/schemas/ImageData" + imageUrl: + type: string + description: "Image URL." + resizeOptions: + $ref: "#/components/schemas/ResizeOptions" + AddImageToPersonResponse: + title: "AddImageToPersonResponse" type: object description: "Image in the response." properties: @@ -156,8 +174,16 @@ components: description: "A free-form object containing person's extended attributes." AddImageToPersonRequest: + title: "AddImageToPersonRequest" type: object description: "Image in the request data, includes image and contentType." + allOf: + - $ref: "./common.yml#/components/schemas/TransactionLabels" + - $ref: "#/components/schemas/AddImageToPersonRequestData" + + AddImageToPersonRequestData: + title: "AddImageToPersonRequestData" + type: object required: - image properties: @@ -165,19 +191,7 @@ components: type: string description: "Session identificator." image: - type: object - description: "Uploaded image." - properties: - contentType: - type: string - description: "Original media type of the uploaded image." - content: - $ref: "./common.yml#/components/schemas/ImageData" - imageUrl: - type: string - description: "Image URL." - resizeOptions: - $ref: "#/components/schemas/ResizeOptions" + $ref: "#/components/schemas/AddImageToPersonRequestImage" threshold: type: number format: float @@ -185,14 +199,25 @@ components: limit: type: integer description: "The maximum number of results to be returned." - tenant: + + AddImageToPersonRequestImage: + title: "AddImageToPersonRequestImage" + type: object + description: "Uploaded image." + properties: + contentType: type: string - description: "A label used to group transactions by customers, applications, or other criteria." - env: + description: "Original media type of the uploaded image." + content: + $ref: "./common.yml#/components/schemas/ImageData" + imageUrl: type: string - description: "A label used to differentiate transactions by development stages." + description: "Image URL." + resizeOptions: + $ref: "#/components/schemas/ResizeOptions" ResizeOptions: + title: "ResizeOptions" type: object description: "Set to resize the original image." properties: @@ -208,6 +233,7 @@ components: description: "Resized image quality, percent." Image: + title: "Image" type: object description: "Image in the response." properties: @@ -239,30 +265,42 @@ components: description: "A free-form object containing person's extended attributes." GroupPage: + title: "GroupPage" allOf: - - type: object - properties: - items: - type: array - description: "Array of Groups that are found during the search." - items: - $ref: "#/components/schemas/Group" - - $ref: './common.yml#/components/schemas/Page' + - $ref: "#/components/schemas/GroupPageItems" + - $ref: "./common.yml#/components/schemas/Page" + + GroupPageItems: + title: "GroupPageItems" + type: object + properties: + items: + type: array + description: "Array of Groups that are found during the search." + items: + $ref: "#/components/schemas/Group" + Group: + title: "Group" allOf: - - $ref: '#/components/schemas/GroupResponse' - - type: object - description: "Additional group data in the response, includes id and createdAt." - properties: - id: - type: string - format: uuid - description: "Group ID." - createdAt: - type: string - description: "Group creation date." + - $ref: "#/components/schemas/GroupResponse" + - $ref: "#/components/schemas/GroupData" + + GroupData: + title: "GroupData" + type: object + description: "Additional group data in the response, includes id and createdAt." + properties: + id: + type: string + format: uuid + description: "Group ID." + createdAt: + type: string + description: "Group creation date." GroupResponse: + title: "GroupResponse" type: object description: "Response group create data, includes name and metadata." properties: @@ -275,6 +313,7 @@ components: description: "A free-form object containing group's extended attributes." GroupToCreate: + title: "GroupToCreate" type: object description: "Request body of the group to create data, includes name and metadata." required: diff --git a/index.yml b/index.yml index ebef727..4126256 100755 --- a/index.yml +++ b/index.yml @@ -1,10 +1,10 @@ -openapi: 3.0.3 +openapi: 3.0.4 info: version: 7.2.0 title: Regula Face SDK Web API x-logo: - url: 'https://static-content.regulaforensics.com/Icons/Logos/Regula-logo.svg' - href: 'https://mobile.regulaforensics.com/' + url: "https://static-content.regulaforensics.com/Icons/Logos/Regula-logo.svg" + href: "https://mobile.regulaforensics.com/" description: | Regula Face SDK is a cross-platform biometric verification solution for a digital identity verification process and image quality assurance. 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. @@ -36,39 +36,41 @@ x-tagGroups: - healthcheck servers: + - url: https://faceapi.regulaforensics.com/ + description: Latest stable Regula face demo endpoint + - url: https://nightly-faceapi.regulaforensics.com/ + description: Nightly Regula face demo endpoint - url: http://localhost:41101/ description: Local on-premise installation - - -# ~1 means '/' +# ~1 means '/', %7B means '{', %7D means '}' paths: /api/match: - $ref: './match.yml#/paths/~1match' + $ref: "./match.yml#/paths/~1match" /api/match_and_search: - $ref: './match_and_search.yml#/paths/~1match_and_search' + $ref: "./match_and_search.yml#/paths/~1match_and_search" /api/detect: - $ref: './detect.yml#/paths/~1detect' + $ref: "./detect.yml#/paths/~1detect" /api/persons: - $ref: './persons.yml#/paths/~1persons' + $ref: "./persons.yml#/paths/~1persons" /api/persons/{personId}: - $ref: './persons.yml#/paths/~1persons~1{personId}' + $ref: "./persons.yml#/paths/~1persons~1%7BpersonId%7D" /api/persons/{personId}/images: - $ref: './persons.yml#/paths/~1persons~1{personId}~1images' + $ref: "./persons.yml#/paths/~1persons~1%7BpersonId%7D~1images" /api/persons/{personId}/images/{imageId}: - $ref: './persons.yml#/paths/~1persons~1{personId}~1images~1{imageId}' + $ref: "./persons.yml#/paths/~1persons~1%7BpersonId%7D~1images~1%7BimageId%7D" /api/persons/{personId}/groups: - $ref: './persons.yml#/paths/~1persons~1{personId}~1groups' + $ref: "./persons.yml#/paths/~1persons~1%7BpersonId%7D~1groups" /api/groups: - $ref: './groups.yml#/paths/~1groups' + $ref: "./groups.yml#/paths/~1groups" /api/groups/{groupId}: - $ref: './groups.yml#/paths/~1groups~1{groupId}' + $ref: "./groups.yml#/paths/~1groups~1%7BgroupId%7D" /api/groups/{groupId}/persons: - $ref: './groups.yml#/paths/~1groups~1{groupId}~1persons' + $ref: "./groups.yml#/paths/~1groups~1%7BgroupId%7D~1persons" /api/search: - $ref: './search.yml#/paths/~1search' + $ref: "./search.yml#/paths/~1search" /api/v2/liveness: - $ref: './liveness.yml#/paths/~1v2~1liveness' + $ref: "./liveness.yml#/paths/~1v2~1liveness" /api/healthz: $ref: "./healthcheck.yml#/paths/~1healthz" /api/readyz: diff --git a/liveness.yml b/liveness.yml index c2498c4..5810616 100644 --- a/liveness.yml +++ b/liveness.yml @@ -1,10 +1,10 @@ -openapi: 3.0.3 +openapi: 3.0.4 paths: /v2/liveness: get: parameters: - - $ref: './common.yml#/components/parameters/transactionId' + - $ref: "./common.yml#/components/parameters/transactionId" tags: - liveness 2.0 summary: 'liveness check' @@ -47,6 +47,7 @@ paths: components: schemas: TransactionInfo: + title: "TransactionInfo" type: object properties: code: @@ -82,15 +83,16 @@ components: $ref: "#/components/schemas/LivenessType" LivenessType: + title: "LivenessType" type: integer description: "Liveness detection can be performed in two modes: active `0` and passive `1`. [Learn more](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/liveness/#active-and-passive-modes)" - default: 0 enum: - 0 - 1 x-enum-varnames: - ACTIVE - PASSIVE + responses: SuccessEmpty: description: "Successful operation, return nothing." diff --git a/match.yml b/match.yml index 38dd05a..d4954ea 100644 --- a/match.yml +++ b/match.yml @@ -1,8 +1,9 @@ -openapi: 3.0.3 +openapi: 3.0.4 + paths: /match: parameters: - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" post: tags: - match @@ -37,14 +38,16 @@ So, if there are two images each of which has two faces in them, the parameters 403: $ref: "./common.yml#/components/responses/BadLicense" -info: - title: Regula FaceSDK Web API - version: 6.1.0 - components: schemas: - MatchRequest: + title: "MatchRequest" + allOf: + - $ref: "./common.yml#/components/schemas/TransactionLabels" + - $ref: "#/components/schemas/MatchRequestData" + + MatchRequestData: + title: "MatchRequestData" type: object required: - images @@ -52,29 +55,26 @@ components: tag: type: string description: "Session identificator, should be unique for each session." - images: + images: type: array description: "An array of images to be processed. At least two images must be provided." items: $ref: "#/components/schemas/MatchImage" outputImageParams: $ref: "./common.yml#/components/schemas/ProcessParam/properties/outputImageParams" - tenant: - type: string - description: "A label used to group transactions by customers, applications, or other criteria." - env: - type: string - description: "A label used to differentiate transactions by development stages." MatchImageIndex: + title: "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." MatchFaceIndex: + title: "MatchFaceIndex" type: number description: "The detected face index number." MatchImage: + title: "MatchImage" type: object required: - data @@ -82,33 +82,39 @@ components: index: $ref: "#/components/schemas/MatchImageIndex" type: - $ref: "#/components/schemas/ImageSource" + $ref: "./common.yml#/components/schemas/ImageSource" data: $ref: "./common.yml#/components/schemas/ImageData" detectAll: $ref: "#/components/schemas/detectAll" MatchResponse: + title: "MatchResponse" allOf: - - $ref: './common.yml#/components/schemas/FaceSDKResult' - - type: object - properties: - detections: - type: array - description: "The detection results." - items: - $ref: "#/components/schemas/MatchImageDetection" - results: - type: array - description: "The comparison results." - items: - $ref: "#/components/schemas/MatchImageResult" - metadata: - type: object - additionalProperties: true - description: "A free-form object containing person's extended attributes." + - $ref: "./common.yml#/components/schemas/FaceSDKResult" + - $ref: "#/components/schemas/MatchResponseData" + + MatchResponseData: + title: "MatchResponseData" + type: object + properties: + detections: + type: array + description: "The detection results." + items: + $ref: "#/components/schemas/MatchImageDetection" + results: + type: array + description: "The comparison results." + items: + $ref: "#/components/schemas/MatchImageResult" + metadata: + type: object + additionalProperties: true + description: "A free-form object containing person's extended attributes." MatchImageResult: + title: "MatchImageResult" type: object required: - firstIndex @@ -119,13 +125,13 @@ components: firstFaceIndex: $ref: "#/components/schemas/MatchFaceIndex" first: - $ref: "#/components/schemas/ImageSource" + $ref: "./common.yml#/components/schemas/ImageSource" secondIndex: $ref: "#/components/schemas/MatchImageIndex" secondFaceIndex: $ref: "#/components/schemas/MatchFaceIndex" second: - $ref: "#/components/schemas/ImageSource" + $ref: "./common.yml#/components/schemas/ImageSource" score: type: number description: "A dimensionless number that shows how similar the compared faces are. 0—absolutely identical faces." @@ -134,6 +140,7 @@ components: description: "The detected faces similarity, %. 100%—absolutely identical faces, 0%—absolutely not identical." MatchImageDetection: + title: "MatchImageDetection" type: object required: - imageIndex @@ -147,9 +154,10 @@ components: imageIndex: $ref: "#/components/schemas/MatchImageIndex" status: - $ref: './common.yml#/components/schemas/FaceSDKResultCode' + $ref: "./common.yml#/components/schemas/FaceSDKResultCode" DetectionFace: + title: "DetectionFace" type: object properties: faceIndex: @@ -174,26 +182,8 @@ components: format: byte description: "Base64-encoded aligned and cropped portrait." - ImageSource: - 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 - - 2 - - 3 - - 4 - - 5 - - 6 - - 7 - x-enum-varnames: - - DOCUMENT_PRINTED - - DOCUMENT_RFID - - LIVE - - DOCUMENT_WITH_LIVE - - EXTERNAL - - GHOST - - BARCODE detectAll: + title: "detectAll" type: boolean description: "Whether to detect all faces in the image. If set to `false`, only the most central face is detected." - default: false \ No newline at end of file + default: false diff --git a/match_and_search.yml b/match_and_search.yml index 6309ec3..82ccda8 100644 --- a/match_and_search.yml +++ b/match_and_search.yml @@ -1,12 +1,13 @@ -openapi: 3.0.3 +openapi: 3.0.4 + paths: /match_and_search: parameters: - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" post: tags: - match - summary: 'match and search (1:1 + 1:N)' + 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. At least two photos are required. If, after processing two or more photos, only one face is detected across them, the match step is skipped, and only the search is carried out." operationId: match_and_search requestBody: @@ -14,19 +15,21 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/MatchAndSearchRequest' + $ref: "#/components/schemas/MatchAndSearchRequest" responses: 200: - description: 'Successful operation; the compare results are returned.' + description: "Successful operation; the compare results are returned." content: application/json: schema: - $ref: '#/components/schemas/MatchAndSearchResponse' + $ref: "#/components/schemas/MatchAndSearchResponse" 403: - $ref: './common.yml#/components/responses/BadLicense' + $ref: "./common.yml#/components/responses/BadLicense" + components: schemas: MatchAndSearchRequest: + title: "MatchAndSearchRequest" type: object properties: tag: @@ -36,15 +39,7 @@ components: type: array description: "An array of images to be processed. At least two images must be provided." items: - type: object - properties: - content: - $ref: './common.yml#/components/schemas/ImageData' - imageUrl: - description: "Image URL." - type: string - type: - $ref: './match.yml#/components/schemas/ImageSource' + $ref: "#/components/schemas/MatchAndSearchRequestImagesItem" groupIds: type: array description: "IDs of the groups in which the search is performed." @@ -64,62 +59,90 @@ components: type: string description: "A label used to differentiate transactions by development stages." + MatchAndSearchRequestImagesItem: + title: "MatchAndSearchRequestImagesItem" + type: object + properties: + content: + $ref: "./common.yml#/components/schemas/ImageData" + imageUrl: + description: "Image URL." + type: string + type: + $ref: "./common.yml#/components/schemas/ImageSource" + MatchAndSearchResponse: + title: "MatchAndSearchResponse" allOf: - - $ref: './common.yml#/components/schemas/FaceSDKResult' - - type: object - properties: - results: - type: array - description: "The match and search results." - items: - $ref: './match.yml#/components/schemas/MatchImageResult' - elapsedTime: - type: number - description: "Server processing time, ms. Does not include the time taken to receive the request or deliver the response." - format: float - example: 1.317137987 - metadata: - type: object - additionalProperties: true - 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: - $ref: './match.yml#/components/schemas/MatchImageIndex' - status: - $ref: './common.yml#/components/schemas/FaceSDKResultCode' + - $ref: "./common.yml#/components/schemas/FaceSDKResult" + - $ref: "#/components/schemas/MatchAndSearchResponseData" + + MatchAndSearchResponseData: + title: "MatchAndSearchResponseData" + type: object + properties: + results: + type: array + description: "The match and search results." + items: + $ref: "./match.yml#/components/schemas/MatchImageResult" + elapsedTime: + type: number + description: "Server processing time, ms. Does not include the time taken to receive the request or deliver the response." + format: float + example: 1.317137987 + metadata: + type: object + additionalProperties: true + description: "A free-form object containing person's extended attributes." + detections: + type: array + description: "The detection results." + items: + $ref: "#/components/schemas/MatchAndSearchResponseDataDetectionsItem" + + MatchAndSearchResponseDataDetectionsItem: + title: "MatchAndSearchResponseDataDetectionsItem" + type: object + properties: + faces: + type: array + description: "Detected faces." + items: + $ref: "#/components/schemas/FacesResponse" + imageIndex: + $ref: "./match.yml#/components/schemas/MatchImageIndex" + status: + $ref: "./common.yml#/components/schemas/FaceSDKResultCode" + PersonWithImages: + title: "PersonWithImages" allOf: - - type: object - properties: - images: - type: array - description: "Detected Persons." - items: - $ref: './search.yml#/definitions/RecognizeImage' - - $ref: './identification.yml#/components/schemas/Person' + - $ref: "#/components/schemas/PersonWithImagesData" + - $ref: "./identification.yml#/components/schemas/Person" + + PersonWithImagesData: + title: "PersonWithImagesData" + type: object + properties: + images: + type: array + description: "Detected Persons." + items: + $ref: "./search.yml#/components/schemas/RecognizeImage" FacesResponse: + title: "FacesResponse" allOf: - - $ref: './match.yml#/components/schemas/DetectionFace' - - type: object - properties: - persons: - type: array - description: "Detected Persons." - items: - $ref: '#/components/schemas/PersonWithImages' - rotationAngle: - type: number - format: float - example: 2.1272900104522705 + - $ref: "./match.yml#/components/schemas/DetectionFace" + - $ref: "#/components/schemas/FacesResponseData" + + FacesResponseData: + title: "FacesResponseData" + type: object + properties: + persons: + type: array + description: "Detected Persons." + items: + $ref: "#/components/schemas/PersonWithImages" diff --git a/openapitools.json b/openapitools.json deleted file mode 100644 index 8ef4cb7..0000000 --- a/openapitools.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json", - "spaces": 2, - "generator-cli": { - "version": "5.0.1" - } -} diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 48e341a..0000000 --- a/package-lock.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "lockfileVersion": 1 -} diff --git a/persons.yml b/persons.yml index 04b2009..5f2a7cb 100644 --- a/persons.yml +++ b/persons.yml @@ -1,10 +1,9 @@ -openapi: 3.0.3 - +openapi: 3.0.4 paths: /persons: parameters: - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" post: tags: - person @@ -21,10 +20,11 @@ paths: $ref: "#/components/responses/SuccessPerson" 400: $ref: "./common.yml#/components/responses/BadRequest" + /persons/{personId}: parameters: - - $ref: '#/components/parameters/personId' - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "#/components/parameters/personId" + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - person @@ -67,30 +67,31 @@ paths: 400: $ref: "./common.yml#/components/responses/BadRequest" 404: - $ref: '#/components/responses/PersonNotFound' + $ref: "#/components/responses/PersonNotFound" + /persons/{personId}/images: parameters: - $ref: '#/components/parameters/personId' - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - person summary: Get person images operationId: get_all_images_by_person_id parameters: - - $ref: './common.yml#/components/parameters/page' - - $ref: './common.yml#/components/parameters/size' + - $ref: "./common.yml#/components/parameters/page" + - $ref: "./common.yml#/components/parameters/size" responses: 200: description: "Successful operation; return all person images." content: application/json: schema: - $ref: "#/definitions/ImagePage" + $ref: "#/components/schemas/ImagePage" 400: $ref: "./common.yml#/components/responses/BadRequest" 404: - $ref: '#/components/responses/PersonNotFound' + $ref: "#/components/responses/PersonNotFound" post: tags: - person @@ -114,21 +115,22 @@ paths: 400: $ref: "./common.yml#/components/responses/BadRequest" 404: - $ref: '#/components/responses/PersonNotFound' + $ref: "#/components/responses/PersonNotFound" + /persons/{personId}/images/{imageId}: parameters: - - $ref: '#/components/parameters/personId' - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "#/components/parameters/personId" + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - person summary: Get person image by id operationId: get_image_of_person parameters: - - $ref: '#/components/parameters/imageId' + - $ref: "#/components/parameters/imageId" responses: 404: - $ref: '#/components/responses/PersonNotFound' + $ref: "#/components/responses/PersonNotFound" description: "Such an image does not exists." 400: $ref: "./common.yml#/components/responses/BadRequest" @@ -146,7 +148,7 @@ paths: summary: Delete image of person operationId: delete_image_of_person parameters: - - $ref: '#/components/parameters/imageId' + - $ref: "#/components/parameters/imageId" responses: 204: $ref: "#/components/responses/SuccessEmpty" @@ -158,18 +160,19 @@ paths: application/json: schema: $ref: "./common.yml#/components/schemas/OperationLog" + /persons/{personId}/groups: parameters: - - $ref: '#/components/parameters/personId' - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "#/components/parameters/personId" + - $ref: "./common.yml#/components/parameters/x-request" get: tags: - person summary: Get person groups operationId: get_all_groups_by_person_id parameters: - - $ref: './common.yml#/components/parameters/page' - - $ref: './common.yml#/components/parameters/size' + - $ref: "./common.yml#/components/parameters/page" + - $ref: "./common.yml#/components/parameters/size" responses: 200: description: "Successful operation; return all groups." @@ -180,9 +183,25 @@ paths: 400: $ref: "./common.yml#/components/responses/BadRequest" 404: - $ref: '#/components/responses/PersonNotFound' + $ref: "#/components/responses/PersonNotFound" components: + schemas: + ImagePage: + title: "ImagePage" + allOf: + - $ref: "./common.yml#/components/schemas/Page" + - $ref: '#/components/schemas/ImagePageItems' + + ImagePageItems: + title: "ImagePageItems" + type: object + properties: + items: + type: array + items: + $ref: "./identification.yml#/components/schemas/Image" + parameters: personId: name: personId @@ -215,15 +234,3 @@ components: application/json: schema: $ref: "./common.yml#/components/schemas/OperationLog" - -definitions: - ImagePage: - allOf: - - $ref: './common.yml#/components/schemas/Page' - - type: object - description: "Image page." - properties: - items: - type: array - items: - $ref: "./identification.yml#/components/schemas/Image" diff --git a/redocly.yaml b/redocly.yaml new file mode 100644 index 0000000..7050b65 --- /dev/null +++ b/redocly.yaml @@ -0,0 +1,12 @@ +openapi: + hideDownloadButton: true + maxDisplayedEnumValues: 5 + expandResponses: 'all' + expandSingleSchemaField: true + jsonSampleExpandLevel: 6 + theme: + logo: + gutter: '20px' + colors: + primary: + main: '#8a53cb' diff --git a/search.yml b/search.yml index c1a3b7e..61ffe2f 100644 --- a/search.yml +++ b/search.yml @@ -1,10 +1,9 @@ -openapi: 3.0.3 - +openapi: 3.0.4 paths: /search: parameters: - - $ref: './common.yml#/components/parameters/x-request' + - $ref: "./common.yml#/components/parameters/x-request" - in: query name: withImages required: false @@ -21,172 +20,186 @@ paths: content: application/json: schema: - $ref: "#/definitions/SearchRequest" + $ref: "#/components/schemas/SearchRequest" responses: 200: description: "Successful operation; the search result is returned." content: application/json: schema: - $ref: "#/definitions/SearchResult" + $ref: "#/components/schemas/SearchResult" 201: description: "New person created with the search photo and the data specified." content: application/json: schema: - $ref: "#/definitions/SearchPerson" + $ref: "#/components/schemas/SearchPerson" 400: $ref: "./identification.yml#/components/responses/SearchBadParamsException" -definitions: - SearchRequest: - allOf: - - $ref: "#/definitions/SearchParameters" - - $ref: "./identification.yml#/components/schemas/ImageFields" - - type: object - properties: - tenant: - type: string - description: "A label used to group transactions by customers, applications, or other criteria." - env: - type: string - description: "A label used to differentiate transactions by development stages." +components: + schemas: + SearchRequest: + title: "SearchRequest" + allOf: + - $ref: "./common.yml#/components/schemas/TransactionLabels" + - $ref: "#/components/schemas/SearchParameters" + - $ref: "./identification.yml#/components/schemas/ImageFields" - SearchParameters: - type: object - description: "Request search data." - properties: - createPerson: - type: object - description: "If a person is not found, a new person entry is created using the descriptor calculated while searching." - properties: - name: + SearchParameters: + title: "SearchParameters" + type: object + description: "Request search data." + properties: + createPerson: + $ref: "#/components/schemas/SearchParametersCreatePerson" + groupIds: + type: array + description: "IDs of the groups in which the search is performed." + items: type: string - description: "Person's name." - metadata: - type: object - additionalProperties: true - description: "A free-form object containing person's extended attributes." - ttl: - type: integer - description: "The lifespan of the Person's records, seconds. Optional." - nullable: true - default: null - groupIds: - type: array - description: "IDs of the groups in which the search is performed." - items: + format: uuid + filter: + $ref: "#/components/schemas/FilterSearchRequest" + + SearchParametersCreatePerson: + title: "SearchParametersCreatePerson" + type: object + description: "If a person is not found, a new person entry is created using the descriptor calculated while searching." + properties: + name: type: string - format: uuid - filter: - $ref: '#/definitions/FilterSearchRequest' + description: "Person's name." + metadata: + type: object + additionalProperties: true + description: "A free-form object containing person's extended attributes." + ttl: + type: integer + description: "The lifespan of the Person's records, seconds. Optional." + default: null - FilterSearchRequest: - type: object - description: "Allows to filter the search results based on the Person's `name`. If enabled, only the search results that meet the filter condition will be returned." - properties: - op: - $ref: '#/definitions/FilterOp' - field: - type: string - description: "`name` of the Person." - value: - type: array - description: "The list of `name` values against which the `field` is compared." - items: + FilterSearchRequest: + title: "FilterSearchRequest" + type: object + description: "Allows to filter the search results based on the Person's `name`. If enabled, only the search results that meet the filter condition will be returned." + properties: + op: + $ref: "#/components/schemas/FilterOp" + field: type: string + description: "`name` of the Person." + value: + type: array + description: "The list of `name` values against which the `field` is compared." + items: + type: string - FilterOp: - type: string - description: "The filter condition, determines the type of comparison to be performed on the `name` values of the Person entity.

When set to `in`, the `name` values of the Person should match any of the values specified in the `value` list.

When set to `nin`, the `name` values of the Person should not match any of the values specified in the `value` list." - enum: - - "in" - - "nin" - x-enum-varnames: - - IN - - NOT_IN + FilterOp: + title: "FilterOp" + type: string + description: "The filter condition, determines the type of comparison to be performed on the `name` values of the Person entity.

When set to `in`, the `name` values of the Person should match any of the values specified in the `value` list.

When set to `nin`, the `name` values of the Person should not match any of the values specified in the `value` list." + enum: + - "in" + - "nin" + x-enum-varnames: + - "IN" + - "NOT_IN" - RecognizeImage: - allOf: - - $ref: "./identification.yml#/components/schemas/Image" - - type: object - properties: - similarity: - type: number - format: float - description: "Similarity score." - distance: - type: number - format: float - description: "Similarity distance score: the lower the distance, the higher the face's similarity." - SearchResult: - type: object - properties: - code: - type: integer - description: "Result code. It is returned only with response 200." - persons: - type: array - description: "Array of Person images. It is returned only with response 200." - items: - $ref: "#/definitions/SearchPerson" - SearchPerson: - allOf: - - $ref: "./identification.yml#/components/schemas/Person" - - type: object - description: "Person data." - properties: - detection: - $ref: "#/definitions/SearchDetection" - images: - type: array - description: "Array of Person images." - items: - $ref: "#/definitions/RecognizeImage" + RecognizeImage: + title: "RecognizeImage" + allOf: + - $ref: "./identification.yml#/components/schemas/Image" + - $ref: "#/components/schemas/RecognizeImageData" + + RecognizeImageData: + title: "RecognizeImageData" + type: object + properties: + similarity: + type: number + format: float + description: "Similarity score." + distance: + type: number + format: float + description: "Similarity distance score: the lower the distance, the higher the face's similarity." + + SearchResult: + title: "SearchResult" + type: object + properties: + code: + type: integer + description: "Result code. It is returned only with response 200." + persons: + type: array + description: "Array of Person images. It is returned only with response 200." + items: + $ref: "#/components/schemas/SearchPerson" - SearchDetection: - type: object - description: "The array of identified persons." - properties: - code: - type: integer - description: "Internal." - crop: - type: string - format: base64 - description: "Base64 of the aligned and cropped portrait." - detectorType: - type: integer - description: "Internal." - hash: - type: string - description: "Internal." - idx: - type: integer - description: "Internal." - image: - type: string - format: base64 - description: "Internal." - landmarks: - description: "Absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips." - type: array - items: - description: "Cartesian points. First element - X-axis coordinate. Second element - Y-axis coordinate." + SearchPerson: + title: "SearchPerson" + allOf: + - $ref: "./identification.yml#/components/schemas/Person" + - $ref: "#/components/schemas/SearchPersonData" + + SearchPersonData: + title: "SearchPersonData" + type: object + properties: + detection: + $ref: "#/components/schemas/SearchDetection" + images: type: array + description: "Array of Person images." items: - type: integer - example: [ x, y ] - example: [ [ x, y ] ] - landmarksType: - type: integer - description: "Internal." - example: 2 - msg: - type: string - description: "Internal." - roi: - $ref: "./common.yml#/components/schemas/FaceRectangular" - versionSDK: - type: string - example: "5.2.245.687" + $ref: "#/components/schemas/RecognizeImage" + + SearchDetection: + title: "SearchDetection" + type: object + description: "The array of identified persons." + properties: + code: + type: integer + description: "Internal." + crop: + type: string + format: base64 + description: "Base64 of the aligned and cropped portrait." + detectorType: + type: integer + description: "Internal." + hash: + type: string + description: "Internal." + idx: + type: integer + description: "Internal." + image: + type: string + format: base64 + description: "Internal." + landmarks: + description: "Absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips." + type: array + items: + description: "Cartesian points. First element - X-axis coordinate. Second element - Y-axis coordinate." + type: array + items: + type: integer + example: [ x, y ] + example: [ [ x, y ] ] + landmarksType: + type: integer + description: "Internal." + example: 2 + msg: + type: string + description: "Internal." + roi: + $ref: "./common.yml#/components/schemas/FaceRectangular" + versionSDK: + type: string + example: "5.2.245.687"