Merged in feature/clientexternalid (pull request #99)

Client External ID * normalizeexternalid * cleanopenapi * cleanopenapi * changingpublic * noprecommit * testing * precommit * processtest * nodb * tests * tests
2025-03-11 16:31:06 +00:00
parent 8e4d66a998
commit 6648cdf1cb
68 changed files with 5171 additions and 1106 deletions
@@ -28,6 +28,7 @@ paths:
      summary: Create a new client
      description: Creates a new client with the provided details.
      requestBody:
+        description: The details required to create a client
        required: true
        content:
          application/json:
@@ -39,19 +40,13 @@ paths:
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/IdMessage"
+                $ref: "#/components/schemas/ClientIDBody"
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /client/{id}:
    parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The ID of the client to retrieve.
+      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: getClient
      tags:
@@ -66,7 +61,7 @@ paths:
              schema:
                $ref: "#/components/schemas/DocClient"
        "400":
-          description: Invalid request parameters.
+          $ref: "#/components/responses/InvalidRequest"
    patch:
      operationId: updateClient
      tags:
@@ -74,6 +69,7 @@ paths:
      summary: Update a client
      description: Updates an existing client with new details.
      requestBody:
+        description: The details to update
        required: true
        content:
          application/json:
@@ -83,7 +79,7 @@ paths:
        "200":
          description: Client updated successfully.
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /query:
    get:
@@ -100,7 +96,7 @@ paths:
              schema:
                $ref: "#/components/schemas/ListQueries"
        "400":
-          description: Invalid request parameters.
+          $ref: "#/components/responses/InvalidRequest"
    post:
      operationId: createQuery
      tags:
@@ -108,6 +104,7 @@ paths:
      summary: Create a new query
      description: Creates a new query with the provided details.
      requestBody:
+        description: The details required to create a query
        required: true
        content:
          application/json:
@@ -121,17 +118,11 @@ paths:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /query/{id}:
    parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The ID of the query.
+      - $ref: "#/components/parameters/QueryID"
    get:
      operationId: getQuery
      tags:
@@ -146,7 +137,7 @@ paths:
              schema:
                $ref: "#/components/schemas/Query"
        "400":
-          description: Invalid request parameters.
+          $ref: "#/components/responses/InvalidRequest"
    patch:
      operationId: updateQuery
      tags:
@@ -154,6 +145,7 @@ paths:
      summary: Update a query
      description: Updates an existing query with new details.
      requestBody:
+        description: The update values for the desired query.
        required: true
        content:
          application/json:
@@ -163,17 +155,11 @@ paths:
        "200":
          description: Query updated successfully.
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /query/{id}/test:
    parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The ID of the query.
+      - $ref: "#/components/parameters/QueryID"
    post:
      operationId: testQuery
      tags:
@@ -181,6 +167,7 @@ paths:
      summary: Test a query
      description: Executes a test run of a query with the provided parameters.
      requestBody:
+        description: The query test requirements.
        required: true
        content:
          application/json:
@@ -194,17 +181,11 @@ paths:
              schema:
                $ref: "#/components/schemas/QueryTestResponse"
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /client/{id}/status:
    parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The client id.
+      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: getStatusByClientId
      tags:
@@ -219,17 +200,11 @@ paths:
              schema:
                $ref: "#/components/schemas/ClientStatusBody"
        "400":
-          description: Invalid request parameters.
+          $ref: "#/components/responses/InvalidRequest"

  /client/{id}/collector:
    parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The client ID for the collector.
+      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: getCollectorByClientId
      tags:
@@ -244,7 +219,7 @@ paths:
              schema:
                $ref: "#/components/schemas/Collector"
        "400":
-          description: Invalid body.
+          $ref: "#/components/responses/InvalidRequest"
    patch:
      operationId: setCollectorByClientId
      tags:
@@ -252,6 +227,7 @@ paths:
      summary: Set a collector
      description: Set client collector with new details.
      requestBody:
+        description: The details to be set for the collector.
        required: true
        content:
          application/json:
@@ -261,17 +237,11 @@ paths:
        "204":
          description: Collector set successfully.
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /client/{id}/documents:
    parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The client ID for the documents.
+      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: listDocumentsByClientId
      tags:
@@ -286,17 +256,37 @@ paths:
              schema:
                $ref: "#/components/schemas/ListDocuments"
        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

  /client/{id}/export:
    parameters:
-      - in: path
-        name: id
+      - $ref: "#/components/parameters/ClientID"
+    post:
+      operationId: triggerExport
+      tags:
+        - ExportService
+      summary: Trigger an export
+      description: Initiates the export process.
+      requestBody:
+        description: The export requirements.
        required: true
-        schema:
-          type: string
-          format: uuid
-        description: The ID of the export.
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExportTrigger"
+      responses:
+        "201":
+          description: Export triggered successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IdMessage"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+
+  /export/{id}:
+    parameters:
+      - $ref: "#/components/parameters/ExportID"
    get:
      operationId: exportState
      tags:
@@ -311,31 +301,77 @@ paths:
              schema:
                $ref: "#/components/schemas/ExportDetails"
        "400":
-          description: Invalid body.
-    post:
-      operationId: triggerExport
-      tags:
-        - ExportService
-      summary: Trigger an export
-      description: Initiates the export process.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/ExportTrigger"
-      responses:
-        "201":
-          description: Export triggered successfully.
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/IdMessage"
-        "400":
-          description: Invalid request body.
+          $ref: "#/components/responses/InvalidRequest"

 components:
+  parameters:
+    ClientID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/ClientID"
+      description: The client ID.
+
+    ExportID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/ExportID"
+      description: The export ID.
+
+    QueryID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/QueryID"
+      description: The ID of the query.
+
+  responses:
+    InvalidRequest:
+      description: Invalid request body.
+
  schemas:
+    ClientID:
+      type: string
+      description: The client external id
+      example: AAA
+
+    ClientUID:
+      type: string
+      format: uuid
+      description: The client internal unique id
+      example: 0195853c-8fdd-77cd-b36c-255241bddd33
+
+    QueryID:
+      type: string
+      format: uuid
+      description: The query id.
+      example: 019580df-ef65-7676-8de9-94435a93337a
+
+    DocumentID:
+      type: string
+      format: uuid
+      description: The document id.
+      example: 019580df-b3f8-7348-9ab1-1e55b3f18ed7
+
+    ExportID:
+      type: string
+      format: uuid
+      description: The export id.
+      example: 019580de-4d51-713c-98ee-464e83811f13
+
+    ClientName:
+      type: string
+      description: The client name
+      example: AArete
+
+    ClientCanSync:
+      type: boolean
+      description: If the client is allowing active syncs
+
    QueryType:
      type: string
      enum:
@@ -343,32 +379,26 @@ components:
        - CONTEXT_FULL
      description: Specifies the type of the query.

+    QueryConfig:
+      type: string
+      description: Configuration for the query.
+
    Query:
+      description: A logic unit of execution.
      type: object
      properties:
        id:
-          type: string
-          format: uuid
-          description: Unique identifier for the query.
+          $ref: "#/components/schemas/QueryID"
        type:
          $ref: "#/components/schemas/QueryType"
        active_version:
-          type: integer
-          format: int32
-          description: The active version of the query.
+          $ref: "#/components/schemas/Version"
        latest_version:
-          type: integer
-          format: int32
-          description: The latest version of the query.
+          $ref: "#/components/schemas/Version"
        config:
-          type: string
-          description: Configuration for the query.
+          $ref: "#/components/schemas/QueryConfig"
        required_queries:
-          type: array
-          items:
-            type: string
-            format: uuid
-          description: List of required query IDs.
+          $ref: "#/components/schemas/RequiredQueryIDs"
      required:
        - id
        - type
@@ -376,6 +406,7 @@ components:
        - latest_version

    ListQueries:
+      description: A set of queries.
      type: object
      properties:
        queries:
@@ -387,55 +418,49 @@ components:
        - queries

    QueryCreate:
+      description: The parameters required to create a query.
      type: object
      properties:
        type:
          $ref: "#/components/schemas/QueryType"
        config:
-          type: string
-          description: Configuration for the new query.
+          $ref: "#/components/schemas/QueryConfig"
        required_queries:
-          type: array
-          items:
-            type: string
-            format: uuid
-          description: List of required query IDs.
+          $ref: "#/components/schemas/RequiredQueryIDs"
      required:
        - type

+    RequiredQueryIDs:
+      type: array
+      items:
+        $ref: "#/components/schemas/QueryID"
+      description: List of required query IDs.
+
    QueryUpdate:
+      description: The properties that may be updated for a query.
      type: object
      properties:
        config:
-          type: string
-          description: Updated configuration for the query.
+          $ref: "#/components/schemas/QueryConfig"
        active_version:
-          type: integer
-          format: int32
-          description: Updated active version.
+          $ref: "#/components/schemas/Version"
        required_queries:
-          type: array
-          items:
-            type: string
-            format: uuid
-          description: Updated list of required query IDs.
+          $ref: "#/components/schemas/RequiredQueryIDs"

    QueryTestRequest:
+      description: The properties for a query test request.
      type: object
      properties:
        document_id:
-          type: string
-          format: uuid
-          description: ID of the document to test against.
+          $ref: "#/components/schemas/DocumentID"
        query_version:
-          type: integer
-          format: int32
-          description: Version of the query to use for testing.
+          $ref: "#/components/schemas/Version"
      required:
        - document_id
        - query_version

    QueryTestResponse:
+      description: The response from a query test.
      type: object
      properties:
        value:
@@ -445,20 +470,20 @@ components:
        - value

    DocClient:
+      description: The properties of a client.
      type: object
      properties:
+        uid:
+          $ref: "#/components/schemas/ClientUID"
        id:
-          type: string
-          format: uuid
-          description: The client id
+          $ref: "#/components/schemas/ClientID"
        name:
-          type: string
-          description: The client name
+          $ref: "#/components/schemas/ClientName"
        can_sync:
-          type: boolean
-          description: If the client is allowing active syncs
+          $ref: "#/components/schemas/ClientCanSync"
      required:
        - id
+        - uid
        - name
        - can_sync

@@ -471,18 +496,23 @@ components:
      description: Specifies the status of a client.

    ClientStatusBody:
+      description: A client status information object.
      type: object
      properties:
-        client_id:
-          type: string
-          format: uuid
-          description: The client id
        status:
          $ref: "#/components/schemas/ClientStatus"
      required:
-        - client_id
        - status

+    ClientIDBody:
+      description: The client id.
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/ClientID"
+      required:
+        - id
+
    ListDocuments:
      type: array
      description: The documents in the client.
@@ -490,12 +520,11 @@ components:
        $ref: "#/components/schemas/Document"

    Document:
+      description: The document properties.
      type: object
      properties:
        id:
-          type: string
-          format: uuid
-          description: The document id
+          $ref: "#/components/schemas/DocumentID"
        bucket:
          type: string
          description: The bucket containing the document
@@ -508,25 +537,28 @@ components:
        - key

    ClientCreate:
+      description: The properties for creation.
      type: object
      properties:
+        id:
+          $ref: "#/components/schemas/ClientID"
        name:
-          type: string
-          description: The client name
+          $ref: "#/components/schemas/ClientName"
      required:
+        - id
        - name

    ClientUpdate:
+      description: The properties that may be updated.
      type: object
      properties:
        name:
-          type: string
-          description: The client name
+          $ref: "#/components/schemas/ClientName"
        can_sync:
-          type: boolean
-          description: If the client is allowing active syncs
+          $ref: "#/components/schemas/ClientCanSync"

    IdMessage:
+      description: A single uuid.
      type: object
      properties:
        id:
@@ -536,34 +568,31 @@ components:
      required:
        - id

+    CodeVersion:
+      type: integer
+      format: int32
+      description: The desired code version.
+
+    Version:
+      type: integer
+      format: int32
+      description: The desired version.
+
    Collector:
      type: object
      properties:
        client_id:
-          type: string
-          format: uuid
-          description: The ID of the associated client.
+          $ref: "#/components/schemas/ClientID"
        active_version:
-          type: integer
-          format: int32
-          description: The active version of the collector.
+          $ref: "#/components/schemas/Version"
        latest_version:
-          type: integer
-          format: int32
-          description: The latest version of the collector.
+          $ref: "#/components/schemas/Version"
        minimum_cleaner_version:
-          type: integer
-          format: int32
-          description: The minimum version for the document cleaner.
+          $ref: "#/components/schemas/CodeVersion"
        minimum_text_version:
-          type: integer
-          format: int32
-          description: The minimum version for the text parser.
+          $ref: "#/components/schemas/CodeVersion"
        fields:
-          type: array
-          description: The fields in the collector.
-          items:
-            $ref: "#/components/schemas/CollectorField"
+          $ref: "#/components/schemas/CollectorFields"
      description: Collector model.
      required:
        - client_id
@@ -573,39 +602,37 @@ components:
        - latest_version
        - active_version

+    CollectorFields:
+      type: array
+      description: The fields in the collector.
+      items:
+        $ref: "#/components/schemas/CollectorField"
+
    CollectorSet:
      type: object
      properties:
        minimum_cleaner_version:
-          type: integer
-          format: int32
-          description: The minimum version for the document cleaner.
+          $ref: "#/components/schemas/CodeVersion"
        minimum_text_version:
-          type: integer
-          format: int32
-          description: The minimum version for the text parser.
+          $ref: "#/components/schemas/CodeVersion"
        active_version:
-          type: integer
-          format: int32
-          description: The active version of the collector.
+          $ref: "#/components/schemas/Version"
        fields:
-          type: array
-          description: The fields in the collector.
-          items:
-            $ref: "#/components/schemas/CollectorField"
+          $ref: "#/components/schemas/CollectorFields"
      description: Payload for updating a Collector.

+    CollectorFieldName:
+      type: string
+      description: The output field name.
+
    CollectorField:
      type: object
      description: The field properties for the collector.
      properties:
        name:
-          type: string
-          description: The output field name.
+          $ref: "#/components/schemas/CollectorFieldName"
        query_id:
-          type: string
-          format: uuid
-          description: The query id that will populate the result.
+          $ref: "#/components/schemas/QueryID"
      required:
        - name
        - query_id
@@ -634,8 +661,7 @@ components:
      type: object
      properties:
        field_name:
-          type: string
-          description: The name of the field in question.
+          $ref: "#/components/schemas/CollectorFieldName"
        condition:
          $ref: "#/components/schemas/FieldFilterCondition"
        values:
@@ -674,9 +700,7 @@ components:
      type: object
      properties:
        client_id:
-          type: string
-          format: uuid
-          description: The client id relative to the export.
+          $ref: "#/components/schemas/ClientID"
        status:
          $ref: "#/components/schemas/ExportStatus"
        output_location: