Merge patch.py into the SchemaGenerator

.gitignore

@@ -14,7 +14,5 @@ local_settings.py
 .coverage
 htmlcov
 ponos
-openapi/*.yml
-!openapi/paths.yml
 *.key
 arkindex/config.yml

MANIFEST.in

@@ -3,6 +3,7 @@ include requirements.txt
 include base/requirements.txt
 include tests-requirements.txt
 include arkindex/documents/fixtures/roles_transkribus.yml
+include arkindex/project/openapi/patch.yml
 recursive-include arkindex/templates *.html
 recursive-include arkindex/templates *.json
 recursive-include arkindex/templates *.txt

arkindex/documents/apps.py

@@ -12,7 +12,7 @@ class DocumentsConfig(AppConfig):
     def _package_version(self, name):
         try:
             with open(os.path.join(settings.BASE_DIR, '..', 'VERSION')) as f:
-                return f.read()
+                return f.read().strip()
         except (OSError, AttributeError, ImproperlyConfigured):
             # File not found or settings module not ready
             pass

arkindex/project/openapi/generators.py

 from pathlib import Path
 from rest_framework.schemas.openapi import SchemaGenerator as BaseSchemaGenerator
 import yaml
+import arkindex
 
 PATCH_FILE = Path(__file__).absolute().parent / 'patch.yml'
 
@@ -11,5 +12,22 @@ class SchemaGenerator(BaseSchemaGenerator):
         with PATCH_FILE.open() as f:
             patch = yaml.safe_load(f)
         schema = super().get_schema(**kwargs)
+        self.patch_paths(schema['paths'], patch.pop('paths', {}))
         schema.update(patch)
+        schema['info']['version'] = arkindex.VERSION
         return schema
+
+    def patch_paths(self, paths, patches):
+        for path_name, methods in patches.items():
+            assert path_name in paths, f'OpenAPI path {path_name} does not exist'
+            path_object = paths[path_name]
+
+            for method, operation_patch in methods.items():
+                assert method in path_object, f'Method {method} on OpenAPI path {path_name} does not exist'
+                operation_object = path_object[method]
+
+                # Update responses separately to allow adding status codes without replacing all of them
+                if 'responses' in operation_patch and 'responses' in operation_object:
+                    operation_object['responses'].update(operation_patch.pop('responses'))
+
+                operation_object.update(operation_patch)

arkindex/project/openapi/patch.yml

@@ -42,3 +42,405 @@ tags:
   - name: users
   - name: management
     description: Admin-only tools
+paths:
+  /api/v1/corpus/:
+    get:
+      description: List corpora with their access rights
+      security: []
+    post:
+      description: Create a new corpus
+  /api/v1/corpus/{id}/:
+    get:
+      description: Retrieve a single corpus
+      security: []
+    put:
+      description: Update a corpus
+    patch:
+      description: Partially update a corpus
+    delete:
+      description: >-
+        Delete a corpus. Requires the "admin" right on the corpus.
+
+        This triggers an asynchronous deletion of a corpus and returns a
+        response immediately; the actual deletion will become visible once
+        the process is completed.
+  /api/v1/corpus/{id}/roles/:
+    get:
+      operationId: ListCorpusRoles
+      description: List all roles of a corpus
+      security: []
+    post:
+      description: Create a new entity role
+      responses:
+        '400':
+          description: An error occured while creating the role.
+          content:
+            application/json:
+              schema:
+                properties:
+                  id:
+                    type: string or array
+                    description: The corpus ID.
+                    readOnly: true
+                  corpus:
+                    type: array
+                    description: Errors that occured during corpus ID field validation.
+                    readOnly: true
+              examples:
+                role-exists:
+                  summary: Role already exists.
+                  value:
+                    id: 55cd009d-cd4b-4ec2-a475-b060f98f9138
+                    corpus:
+                      - Role already exists in this corpus
+  /api/v1/corpus/{id}/ml-stats/:
+    delete:
+      # Will need https://gitlab.com/arkindex/backend/-/issues/86 to be removed
+      operationId: DestroyCorpusMLResults
+      description: Delete machine learning results on all elements of a corpus.
+  /api/v1/element/{id}/:
+    get:
+      description: Retrieve a single element's informations and metadata
+      security: []
+    patch:
+      description: Rename an element
+    put:
+      description: Rename an element
+    delete:
+      description: Delete a childless element
+  /api/v1/element/{id}/ml-stats/:
+    delete:
+      # Will need https://gitlab.com/arkindex/backend/-/issues/86 to be removed
+      operationId: DestroyElementMLResults
+      description: Delete machine learning results on an element and its direct children.
+  /api/v1/elements/selection/:
+    delete:
+      operationId: RemoveSelection
+      description: Remove a specific element or delete any selection
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                id:
+                  format: uuid
+                  type: string
+        x-name: body
+    get:
+      operationId: ListSelection
+      description: List all selected elements
+    post:
+      operationId: AddSelection
+      description: Add specific elements
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                ids:
+                  items:
+                    format: uuid
+                    type: string
+                  type: array
+                  uniqueItems: true
+              required:
+              - ids
+        x-name: body
+  /api/v1/element/{child}/parent/{parent}/:
+    post:
+      operationId: CreateElementParent
+      description: Link an element to a new parent
+    delete:
+      operationId: DestroyElementParent
+      description: Delete the relation between an element and one of its parents
+  /api/v1/entity/{id}/:
+    get:
+      security: []
+    delete:
+      description: Delete an entity
+    patch:
+      description: Partially update an entity
+    put:
+      description: Update an entity
+  /api/v1/image/:
+    post:
+      responses:
+        '400':
+          description: An error occured while validating the image.
+          content:
+            application/json:
+              schema:
+                properties:
+                  detail:
+                    type: string
+                    description: A generic error message when an error occurs outside of a specific field.
+                    readOnly: true
+                  id:
+                    type: string
+                    description: UUID of an existing image, if the error comes from a duplicate hash.
+                    readOnly: true
+                  hash:
+                    type: array
+                    description: One or more error messages for errors when validating the image hash.
+                    readOnly: true
+                  datafile:
+                    type: array
+                    description: One or more error messages for errors when validating the optional DataFile link.
+                    readOnly: true
+              examples:
+                image-exists:
+                  summary: An error where an image with this hash already exists, including the existing image's UUID.
+                  value:
+                    hash:
+                      - Image with this hash already exists
+                    id: 3cc2e9e0-4172-44b1-8d65-bc3fffd076dc
+  /api/v1/image/{id}/:
+    get:
+      description: Retrieve an image
+    put:
+      description: Update an image's status
+    patch:
+      description: Update an image's status
+  /api/v1/imports/file/{id}/:
+    get:
+      description: Get an uploaded file's metadata
+    patch:
+      description: Update a datafile's status
+    put:
+      description: Update a datafile's status
+    delete:
+      description: Delete an uploaded file
+  /api/v1/imports/repos/search/{id}/:
+    post:
+      description: >-
+        Using the given OAuth credentials, this links an external Git repository
+        to Arkindex, connects a push hook and starts an initial import.
+  /api/v1/imports/repos/{id}/:
+    delete:
+      description: Delete a repository
+  /api/v1/imports/upload/{id}/:
+    post:
+      responses:
+        '400':
+          description: An error occured while validating the file.
+          content:
+            application/json:
+              schema:
+                properties:
+                  detail:
+                    type: string
+                    description: A generic error message when an error occurs outside of a specific field.
+                    readOnly: true
+                  id:
+                    type: string
+                    description: UUID of an existing DataFile, if the error  comes from a duplicated upload.
+                    readOnly: true
+                  file:
+                    type: array
+                    description: One or more error messages for errors when validating the file itself.
+                    readOnly: true
+                  corpus:
+                    type: array
+                    description: One or more error messages for errors when validating the destination corpus ID.
+                    readOnly: true
+              examples:
+                file-exists:
+                  summary: An error where the data file already exists, including the existing file's UUID.
+                  value:
+                    file:
+                      - File already exists
+                    id: 3cc2e9e0-4172-44b1-8d65-bc3fffd076dc
+  /api/v1/imports/files/create/:
+    post:
+      responses:
+        '400':
+          description: An error occured while creating the data file.
+          content:
+            application/json:
+              schema:
+                properties:
+                  detail:
+                    type: string
+                    description: A generic error message when an error occurs outside of a specific field.
+                    readOnly: true
+                  hash:
+                    type: array
+                    description: Errors that occured during hash field validation.
+                    readOnly: true
+                  corpus:
+                    type: array
+                    description: Errors that occured during corpus ID field validation.
+                    readOnly: true
+                  name:
+                    type: array
+                    description: Errors that occured during name field validation.
+                    readOnly: true
+                  size:
+                    type: array
+                    description: Errors that occured during size field validation.
+                    readOnly: true
+                  id:
+                    type: string
+                    description: UUID of existing DataFile, if the error comes from a duplicated creation.
+                    readOnly: true
+                  status:
+                    type: string
+                    description: Status of existing DataFile, if the error comes from a duplicated creation.
+                    readOnly: true
+                  s3_put_url:
+                    type: string
+                    description: Signed url used to upload file content to remote server, if the error comes from a duplicated creation and file status is not checked.
+                    readOnly: true
+                  s3_url:
+                    type: string
+                    description: Remote file url, if the error comes from a duplicated creation and file status is checked.
+                    readOnly: true
+              examples:
+                file-exists:
+                  summary: Data file already exists. Response include existing file's UUID, status and remote server PUT url to upload file content.
+                  value:
+                    hash:
+                      - DataFile with this hash already exists
+                    id: 55cd009d-cd4b-4ec2-a475-b060f98f9138
+                    status: unchecked
+                    s3_put_url: https://remote-server.net/staging/55cd009d-cd4b-4ec2-a475-b060f98f9138?Credential=mycredential&Signature=mysignature
+  /api/v1/imports/{id}/:
+    delete:
+      description: Delete a data import. Cannot be used on currently running data imports.
+  /api/v1/oauth/credentials/{id}/:
+    delete:
+      description: Delete OAuth credentials. This may disable access to some Git repositories.
+  /api/v1/oauth/providers/{provider}/signin/:
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                properties:
+                  url:
+                    type: string
+                    format: uri
+                    description: URL to the authorization endpoint.
+                    readOnly: true
+  /api/v1/region/bulk/:
+    post:
+      operationId: CreateRegions
+    put:
+      operationId: UpdateRegions
+      description: Add new regions from a machine learning tool; if this tool already has any regions on this element, they are deleted.
+  /api/v1/transcription/bulk/:
+    put:
+      description: >-
+        Replace all existing transcriptions from a given recognizer on a page
+        with other transcriptions.
+  /api/v1/metadata/{id}/:
+    get:
+      operationId: RetrieveMetaData
+      description: Retrieve an existing metadata
+    patch:
+      operationId: PartialUpdateMetaData
+      description: Partially update an existing metadata
+    put:
+      operationId: UpdateMetaData
+      description: Update an existing metadata
+    delete:
+      operationId: DestroyMetaData
+      description: Delete an existing metadata
+  /api/v1/user/:
+    get:
+      description: Retrieve information about the authenticated user
+    patch:
+      description: Update a user's password. This action is not allowed to users without confirmed e-mails.
+    put:
+      description: Update a user's password. This action is not allowed to users without confirmed e-mails.
+    delete:
+      operationId: Logout
+      description: Log out from the API
+  /ponos/v1/agent/:
+    post:
+      description: Register a Ponos agent
+      security: []
+      tags:
+        - ponos
+  /ponos/v1/agent/actions/:
+    get:
+      description: Retrieve any actions the current agent should perform
+      security:
+        - agentAuth: []
+      tags:
+        - ponos
+  /ponos/v1/agent/refresh/:
+    post:
+      operationId: RefreshAgentToken
+      description: Refresh a Ponos agent token when it expires
+      security:
+        - agentAuth: []
+      tags:
+        - ponos
+  /ponos/v1/public-key/:
+    get:
+      operationId: GetPublicKey
+      description: Get the server's public key.
+      security: []
+      tags:
+        - ponos
+      responses:
+        '200':
+          content:
+            application/x-pem-file:
+              schema:
+                type: string
+              example: |-
+                -----BEGIN PUBLIC KEY-----
+                MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEmK2L6lwGzSVZwFSo0eR1z4XV6jJwjeWK
+                YCiPKdMcQnn6u5J016k9U8xZm6XyFnmgvkhnC3wreGBTFzwLCLZCD+F3vo5x8ivz
+                aTgNWsA3WFlqjSIEGz+PAVHSNMobBaJm
+                -----END PUBLIC KEY-----
+  /ponos/v1/task/{id}/:
+    get:
+      description: Retrieve a Ponos task status
+      security: []
+      tags:
+        - ponos
+    put:
+      description: Update a task
+      security:
+        - agentAuth: []
+      tags:
+        - ponos
+    patch:
+      description: Partially update a task
+      security:
+        - agentAuth: []
+      tags:
+        - ponos
+  /ponos/v1/task/{id}/artifacts/:
+    get:
+      description: List all the artifacts of the task
+      security:
+        - agentAuth: []
+      tags:
+        - ponos
+  /ponos/v1/task/{id}/definition/:
+    get:
+      description: Retrieve a Ponos task
+      operationId: RetrieveTaskDefinition
+      security:
+        - agentAuth: []
+      tags:
+        - ponos
+  /ponos/v1/workflow/{id}/:
+    get:
+      description: Retrieve a Ponos workflow status
+      security: []
+      tags:
+        - ponos
+    patch:
+      description: Partially update a workflow
+      tags:
+      - ponos
+    put:
+      description: Update a workflow's status and tasks
+      tags:
+      - ponos

arkindex/project/openapi/schemas.py

@@ -7,7 +7,7 @@ class AutoSchema(BaseAutoSchema):
     """
     A custom view schema generator.
     The docs on OpenAPI generation are currently very incomplete.
-    If you need to implement more features to avoid the "patch.py" and allow
+    If you need to implement more features to avoid the "patch.yml" and allow
     views to customize their OpenAPI schemas by themselves, you may see for
     yourself how DRF does the schema generation:
     https://github.com/encode/django-rest-framework/blob/master/rest_framework/schemas/openapi.py

arkindex/project/tests/test_openapi.py

 from unittest import TestCase
+from unittest.mock import patch
 from django.test import RequestFactory
 from rest_framework import serializers
 from rest_framework.request import Request
 from rest_framework.views import APIView
-from rest_framework.schemas.openapi import SchemaGenerator
 from arkindex.project.serializer_fields import EnumField
-from arkindex.project.openapi import AutoSchema
+from arkindex.project.openapi import AutoSchema, SchemaGenerator
 from arkindex.project.mixins import DeprecatedAutoSchema
 from arkindex_common.enums import DataImportMode
 import warnings
@@ -370,3 +370,87 @@ class TestOpenAPI(TestCase):
                 }
             }
         )
+
+    @patch('arkindex.project.openapi.generators.arkindex.VERSION', new='0.0')
+    @patch('arkindex.project.openapi.generators.yaml.safe_load', return_value={})
+    def test_auto_version(self, mock):
+        """
+        Ensure the schema version is set to the auto-detected backend's version
+        """
+        schema = SchemaGenerator().get_schema()
+        self.assertEqual(schema['info']['version'], '0.0')
+
+    def test_patch_paths_assertions(self):
+        gen = SchemaGenerator()
+
+        with self.assertRaisesRegex(AssertionError, 'OpenAPI path /somewhere/ does not exist'):
+            gen.patch_paths(
+                paths={},
+                patches={'/somewhere/': {}}
+            )
+
+        with self.assertRaisesRegex(AssertionError, 'Method patch on OpenAPI path /somewhere/ does not exist'):
+            gen.patch_paths(
+                paths={
+                    '/somewhere/': {
+                        'get': {}
+                    }
+                },
+                patches={
+                    '/somewhere/': {
+                        'patch': {}
+                    }
+                }
+            )
+
+    def test_patch_paths(self):
+        patches = {
+            '/somewhere/': {
+                'get': {
+                    'operationId': 'PatchedSomewhere'
+                },
+                'post': {
+                    'responses': {
+                        '409': {
+                            'description': 'Conflict'
+                        }
+                    }
+                }
+            }
+        }
+        expected = {
+            '/somewhere/': {
+                'get': {
+                    'operationId': 'PatchedSomewhere'
+                },
+                'post': {
+                    'operationId': 'PostSomewhere',
+                    'responses': {
+                        '418': {
+                            'description': "I'm a teapot"
+                        },
+                        '409': {
+                            'description': 'Conflict'
+                        }
+                    }
+                }
+            }
+        }
+        actual = {
+            '/somewhere/': {
+                'get': {
+                    'operationId': 'GetSomewhere',
+                },
+                'post': {
+                    'operationId': 'PostSomewhere',
+                    'responses': {
+                        '418': {
+                            'description': "I'm a teapot",
+                        }
+                    }
+                }
+            }
+        }
+        SchemaGenerator().patch_paths(actual, patches)
+
+        self.assertDictEqual(actual, expected)

ci/openapi.sh

@@ -2,5 +2,4 @@
 mkdir -p output
 pip install -e .
 pip install uritemplate==3 apistar>=0.7.2
-PONOS_DATA_DIR=/tmp arkindex/manage.py generateschema --generator_class arkindex.project.openapi.SchemaGenerator > output/original.yml
-openapi/patch.py openapi/paths.yml output/original.yml > output/schema.yml
+PONOS_DATA_DIR=/tmp arkindex/manage.py generateschema --generator_class arkindex.project.openapi.SchemaGenerator > output/schema.yml

openapi/patch.py

-#!/usr/bin/env python3
-import argparse
-import apistar
-import os.path
-import pkg_resources
-import sys
-import yaml
-
-BASE_DIR = os.path.dirname(os.path.abspath(__file__))
-
-
-def get_args():
-    parser = argparse.ArgumentParser()
-    parser.add_argument(
-        'patch',
-        help="File describing patches to make on the schema's paths",
-        type=argparse.FileType('r'),
-    )
-    parser.add_argument(
-        'original',
-        help='Generated OpenAPI schema',
-        type=argparse.FileType('r'),
-        nargs='?',
-        default=sys.stdin,
-    )
-    parser.add_argument(
-        'output',
-        help='Destination file',
-        type=argparse.FileType('w'),
-        nargs='?',
-        default=sys.stdout,
-    )
-    args = vars(parser.parse_args())
-
-    # Load YAML files
-    args['original'] = yaml.safe_load(args['original'])
-    args['patch'] = yaml.safe_load(args['patch'])
-    return args
-
-
-def update_schema(schema, paths):
-    """
-    Perform updates on an OpenAPI schema's paths using another YAML file describing patches.
-    In paths, each operation has its keys updated; the whole operation is not overwritten.
-    Same goes for an operation's responses.
-    """
-    # Update each method separately
-    for path, methods in paths.items():
-        if path not in schema['paths']:
-            print('Creating path {}'.format(path), file=sys.stderr)
-            schema['paths'][path] = {}
-
-        for method, operation in methods.items():
-            print(
-                '{} method {} on path {}'.format(
-                    'Updating' if method in schema['paths'][path] else 'Creating',
-                    method,
-                    path,
-                ),
-                file=sys.stderr,
-            )
-            schema['paths'][path].setdefault(method, {})
-
-            # Update responses separately in each method
-            if 'responses' in operation and 'responses' in schema['paths'][path][method]:
-                schema['paths'][path][method]['responses'].update(operation.pop('responses'))
-
-            schema['paths'][path][method].update(operation)
-
-    # Set the API version to the Arkindex package version
-    try:
-        # Try with the VERSION file
-        with open(os.path.join(BASE_DIR, '..', 'VERSION')) as f:
-            ark_version = f.read().strip()
-    except FileNotFoundError:
-        # Fall back to the pip package version
-        ark_version = pkg_resources.get_distribution('arkindex').version
-
-    schema.setdefault('info', {})
-    schema['info']['version'] = ark_version
-
-    return schema
-
-
-def print_endpoints(schema):
-    """
-    Output a list of all endpoints with their operation IDs and security settings to stderr
-    """
-    for path, methods in schema['paths'].items():
-        print(path, file=sys.stderr)
-        for method, operation in methods.items():
-            security = operation.get('security')
-            auth = 'Custom'
-            if security is None:
-                auth = 'Default'
-            elif security == []:
-                auth = 'No'
-
-            print('  {}: {} - {} authentication'.format(
-                method,
-                operation.get('operationId', 'No operation ID!'),
-                auth,
-            ), file=sys.stderr)
-
-
-def main():
-    args = get_args()
-    schema = update_schema(args['original'], args['patch'])
-    print_endpoints(schema)
-    apistar.validate(schema)
-    yaml.dump(schema, args['output'], default_flow_style=False)
-
-
-if __name__ == '__main__':
-    main()

openapi/paths.yml

-/api/v1/corpus/:
-  get:
-    description: List corpora with their access rights
-    security: []
-  post:
-    description: Create a new corpus
-/api/v1/corpus/{id}/:
-  get:
-    description: Retrieve a single corpus
-    security: []
-  put:
-    description: Update a corpus
-  patch:
-    description: Partially update a corpus
-  delete:
-    description: >-
-      Delete a corpus. Requires the "admin" right on the corpus.
-
-      This triggers an asynchronous deletion of a corpus and returns a
-      response immediately; the actual deletion will become visible once
-      the process is completed.
-/api/v1/corpus/{id}/roles/:
-  get:
-    operationId: ListCorpusRoles
-    description: List all roles of a corpus
-    security: []
-  post:
-    description: Create a new entity role
-    responses:
-      '400':
-        description: An error occured while creating the role.
-        content:
-          application/json:
-            schema:
-              properties:
-                id:
-                  type: string or array
-                  description: The corpus ID.
-                  readOnly: true
-                corpus:
-                  type: array
-                  description: Errors that occured during corpus ID field validation.
-                  readOnly: true
-            examples:
-              role-exists:
-                summary: Role already exists.
-                value:
-                  id: 55cd009d-cd4b-4ec2-a475-b060f98f9138
-                  corpus:
-                    - Role already exists in this corpus
-/api/v1/corpus/{id}/ml-stats/:
-  delete:
-    # Will need https://trello.com/c/f2K4j50S/ to be removed
-    operationId: DestroyCorpusMLResults
-    description: Delete machine learning results on all elements of a corpus.
-/api/v1/element/{id}/:
-  get:
-    description: Retrieve a single element's informations and metadata
-    security: []
-  patch:
-    description: Rename an element
-  put:
-    description: Rename an element
-  delete:
-    description: Delete a childless element
-/api/v1/element/{id}/ml-stats/:
-  delete:
-    # Will need https://trello.com/c/f2K4j50S/ to be removed
-    operationId: DestroyElementMLResults
-    description: Delete machine learning results on an element and its direct children.
-/api/v1/elements/selection/:
-  delete:
-    operationId: RemoveSelection
-    description: Remove a specific element or delete any selection
-    requestBody:
-      content:
-        application/json:
-          schema:
-            properties:
-              id:
-                format: uuid
-                type: string
-      x-name: body
-  get:
-    operationId: ListSelection
-    description: List all selected elements
-  post:
-    operationId: AddSelection
-    description: Add specific elements
-    requestBody:
-      content:
-        application/json:
-          schema:
-            properties:
-              ids:
-                items:
-                  format: uuid
-                  type: string
-                type: array
-                uniqueItems: true
-            required:
-            - ids
-      x-name: body
-/api/v1/element/{child}/parent/{parent}/:
-  post:
-    operationId: CreateElementParent
-    description: Link an element to a new parent
-  delete:
-    operationId: DestroyElementParent
-    description: Delete the relation between an element and one of its parents
-/api/v1/entity/{id}/:
-  get:
-    security: []
-  delete:
-    description: Delete an entity
-  patch:
-    description: Partially update an entity
-  put:
-    description: Update an entity
-/api/v1/image/:
-  post:
-    responses:
-      '400':
-        description: An error occured while validating the image.
-        content:
-          application/json:
-            schema:
-              properties:
-                detail:
-                  type: string
-                  description: A generic error message when an error occurs outside of a specific field.
-                  readOnly: true
-                id:
-                  type: string
-                  description: UUID of an existing image, if the error comes from a duplicate hash.
-                  readOnly: true
-                hash:
-                  type: array
-                  description: One or more error messages for errors when validating the image hash.
-                  readOnly: true
-                datafile:
-                  type: array
-                  description: One or more error messages for errors when validating the optional DataFile link.
-                  readOnly: true
-            examples:
-              image-exists:
-                summary: An error where an image with this hash already exists, including the existing image's UUID.
-                value:
-                  hash:
-                    - Image with this hash already exists
-                  id: 3cc2e9e0-4172-44b1-8d65-bc3fffd076dc
-/api/v1/image/{id}/:
-  get:
-    description: Retrieve an image
-  put:
-    description: Update an image's status
-  patch:
-    description: Update an image's status
-/api/v1/imports/file/{id}/:
-  get:
-    description: Get an uploaded file's metadata
-  patch:
-    description: Update a datafile's status
-  put:
-    description: Update a datafile's status
-  delete:
-    description: Delete an uploaded file
-/api/v1/imports/repos/search/{id}/:
-  post:
-    description: >-
-      Using the given OAuth credentials, this links an external Git repository
-      to Arkindex, connects a push hook and starts an initial import.
-/api/v1/imports/repos/{id}/:
-  delete:
-    description: Delete a repository
-/api/v1/imports/upload/{id}/:
-  post:
-    responses:
-      '400':
-        description: An error occured while validating the file.
-        content:
-          application/json:
-            schema:
-              properties:
-                detail:
-                  type: string
-                  description: A generic error message when an error occurs outside of a specific field.
-                  readOnly: true
-                id:
-                  type: string
-                  description: UUID of an existing DataFile, if the error  comes from a duplicated upload.
-                  readOnly: true
-                file:
-                  type: array
-                  description: One or more error messages for errors when validating the file itself.
-                  readOnly: true
-                corpus:
-                  type: array
-                  description: One or more error messages for errors when validating the destination corpus ID.
-                  readOnly: true
-            examples:
-              file-exists:
-                summary: An error where the data file already exists, including the existing file's UUID.
-                value:
-                  file:
-                    - File already exists
-                  id: 3cc2e9e0-4172-44b1-8d65-bc3fffd076dc
-/api/v1/imports/files/create/:
-  post:
-    responses:
-      '400':
-        description: An error occured while creating the data file.
-        content:
-          application/json:
-            schema:
-              properties:
-                detail:
-                  type: string
-                  description: A generic error message when an error occurs outside of a specific field.
-                  readOnly: true
-                hash:
-                  type: array
-                  description: Errors that occured during hash field validation.
-                  readOnly: true
-                corpus:
-                  type: array
-                  description: Errors that occured during corpus ID field validation.
-                  readOnly: true
-                name:
-                  type: array
-                  description: Errors that occured during name field validation.
-                  readOnly: true
-                size:
-                  type: array
-                  description: Errors that occured during size field validation.
-                  readOnly: true
-                id:
-                  type: string
-                  description: UUID of existing DataFile, if the error comes from a duplicated creation.
-                  readOnly: true
-                status:
-                  type: string
-                  description: Status of existing DataFile, if the error comes from a duplicated creation.
-                  readOnly: true
-                s3_put_url:
-                  type: string
-                  description: Signed url used to upload file content to remote server, if the error comes from a duplicated creation and file status is not checked.
-                  readOnly: true
-                s3_url:
-                  type: string
-                  description: Remote file url, if the error comes from a duplicated creation and file status is checked.
-                  readOnly: true
-            examples:
-              file-exists:
-                summary: Data file already exists. Response include existing file's UUID, status and remote server PUT url to upload file content.
-                value:
-                  hash:
-                    - DataFile with this hash already exists
-                  id: 55cd009d-cd4b-4ec2-a475-b060f98f9138
-                  status: unchecked
-                  s3_put_url: https://remote-server.net/staging/55cd009d-cd4b-4ec2-a475-b060f98f9138?Credential=mycredential&Signature=mysignature
-/api/v1/imports/{id}/:
-  delete:
-    description: Delete a data import. Cannot be used on currently running data imports.
-/api/v1/oauth/credentials/{id}/:
-  delete:
-    description: Delete OAuth credentials. This may disable access to some Git repositories.
-/api/v1/oauth/providers/{provider}/signin/:
-  get:
-    responses:
-      '200':
-        content:
-          application/json:
-            schema:
-              properties:
-                url:
-                  type: string
-                  format: uri
-                  description: URL to the authorization endpoint.
-                  readOnly: true
-/api/v1/region/bulk/:
-  post:
-    operationId: CreateRegions
-  put:
-    operationId: UpdateRegions
-    description: Add new regions from a machine learning tool; if this tool already has any regions on this element, they are deleted.
-/api/v1/transcription/bulk/:
-  put:
-    description: >-
-      Replace all existing transcriptions from a given recognizer on a page
-      with other transcriptions.
-/api/v1/metadata/{id}/:
-  get:
-    operationId: RetrieveMetaData
-    description: Retrieve an existing metadata
-  patch:
-    operationId: PartialUpdateMetaData
-    description: Partially update an existing metadata
-  put:
-    operationId: UpdateMetaData
-    description: Update an existing metadata
-  delete:
-    operationId: DestroyMetaData
-    description: Delete an existing metadata
-/api/v1/user/:
-  get:
-    description: Retrieve information about the authenticated user
-  patch:
-    description: Update a user's password. This action is not allowed to users without confirmed e-mails.
-  put:
-    description: Update a user's password. This action is not allowed to users without confirmed e-mails.
-  delete:
-    operationId: Logout
-    description: Log out from the API
-/ponos/v1/agent/:
-  post:
-    description: Register a Ponos agent
-    security: []
-    tags:
-      - ponos
-/ponos/v1/agent/actions/:
-  get:
-    description: Retrieve any actions the current agent should perform
-    security:
-      - agentAuth: []
-    tags:
-      - ponos
-/ponos/v1/agent/refresh/:
-  post:
-    operationId: RefreshAgentToken
-    description: Refresh a Ponos agent token when it expires
-    security:
-      - agentAuth: []
-    tags:
-      - ponos
-/ponos/v1/public-key/:
-  get:
-    operationId: GetPublicKey
-    description: Get the server's public key.
-    security: []
-    tags:
-      - ponos
-    responses:
-      '200':
-        content:
-          application/x-pem-file:
-            schema:
-              type: string
-            example: |-
-              -----BEGIN PUBLIC KEY-----
-              MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEmK2L6lwGzSVZwFSo0eR1z4XV6jJwjeWK
-              YCiPKdMcQnn6u5J016k9U8xZm6XyFnmgvkhnC3wreGBTFzwLCLZCD+F3vo5x8ivz
-              aTgNWsA3WFlqjSIEGz+PAVHSNMobBaJm
-              -----END PUBLIC KEY-----
-/ponos/v1/task/{id}/:
-  get:
-    description: Retrieve a Ponos task status
-    security: []
-    tags:
-      - ponos
-  put:
-    description: Update a task
-    security:
-      - agentAuth: []
-    tags:
-      - ponos
-  patch:
-    description: Partially update a task
-    security:
-      - agentAuth: []
-    tags:
-      - ponos
-/ponos/v1/task/{id}/artifacts/:
-  get:
-    description: List all the artifacts of the task
-    security:
-      - agentAuth: []
-    tags:
-      - ponos
-/ponos/v1/task/{id}/definition/:
-  get:
-    description: Retrieve a Ponos task
-    operationId: RetrieveTaskDefinition
-    security:
-      - agentAuth: []
-    tags:
-      - ponos
-/ponos/v1/workflow/{id}/:
-  get:
-    description: Retrieve a Ponos workflow status
-    security: []
-    tags:
-      - ponos
-  patch:
-    description: Partially update a workflow
-    tags:
-    - ponos
-  put:
-    description: Update a workflow's status and tasks
-    tags:
-    - ponos