Merged in feature/openapiowasp (pull request #101)

Remove OWASP Errors * started * somewarns * somewarns * gen
2025-03-12 00:59:58 +00:00
parent bbd86fb4ea
commit d60eb9b16b
4 changed files with 256 additions and 57 deletions
@@ -3,9 +3,9 @@ openapi: 3.0.3
 info:
  title: Query Orchestration API
  description: API documentation for the Query Orchestration services.
-  version: 1.0.0
+  version: 0.0.1
 servers:
-  - url: https://api.example.com/v1
+  - url: https://doczy.com/v1
    description: Production server
 tags:
  - name: ClientService
@@ -27,6 +27,8 @@ paths:
        - ClientService
      summary: Create a new client
      description: Creates a new client with the provided details.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The details required to create a client
        required: true
@@ -37,12 +39,17 @@ paths:
      responses:
        "201":
          description: Client created successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientIDBody"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /client/{id}:
    parameters:
@@ -56,18 +63,25 @@ paths:
      responses:
        "200":
          description: Client details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocClient"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
    patch:
      operationId: updateClient
      tags:
        - ClientService
      summary: Update a client
      description: Updates an existing client with new details.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The details to update
        required: true
@@ -78,8 +92,13 @@ paths:
      responses:
        "200":
          description: Client updated successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /query:
    get:
@@ -88,21 +107,30 @@ paths:
        - QueryService
      summary: List queries
      description: Retrieves a list of queries based on filter criteria.
+      security:
+        - placeholderAuth: []
      responses:
        "200":
          description: A list of queries.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListQueries"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
    post:
      operationId: createQuery
      tags:
        - QueryService
      summary: Create a new query
      description: Creates a new query with the provided details.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The details required to create a query
        required: true
@@ -113,12 +141,17 @@ paths:
      responses:
        "201":
          description: Query created successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /query/{id}:
    parameters:
@@ -129,21 +162,30 @@ paths:
        - QueryService
      summary: Get a query by ID
      description: Retrieves a specific query by its ID.
+      security:
+        - placeholderAuth: []
      responses:
        "200":
          description: Query details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Query"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
    patch:
      operationId: updateQuery
      tags:
        - QueryService
      summary: Update a query
      description: Updates an existing query with new details.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The update values for the desired query.
        required: true
@@ -154,8 +196,13 @@ paths:
      responses:
        "200":
          description: Query updated successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /query/{id}/test:
    parameters:
@@ -166,6 +213,8 @@ paths:
        - QueryService
      summary: Test a query
      description: Executes a test run of a query with the provided parameters.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The query test requirements.
        required: true
@@ -176,12 +225,17 @@ paths:
      responses:
        "200":
          description: Test result.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryTestResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /client/{id}/status:
    parameters:
@@ -192,15 +246,22 @@ paths:
        - ClientService
      summary: Get client sync status
      description: Retrieves the sync status by its client ID.
+      security:
+        - placeholderAuth: []
      responses:
        "200":
          description: Client status details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientStatusBody"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /client/{id}/collector:
    parameters:
@@ -211,21 +272,30 @@ paths:
        - CollectorService
      summary: Get a collector by client ID
      description: Retrieves a specific collector by its client ID.
+      security:
+        - placeholderAuth: []
      responses:
        "200":
          description: Collector details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collector"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
    patch:
      operationId: setCollectorByClientId
      tags:
        - CollectorService
      summary: Set a collector
      description: Set client collector with new details.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The details to be set for the collector.
        required: true
@@ -236,8 +306,13 @@ paths:
      responses:
        "204":
          description: Collector set successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /client/{id}/documents:
    parameters:
@@ -248,15 +323,22 @@ paths:
        - DocumentsService
      summary: List the documents for a client
      description: Retrieves the list of documents by the client ID.
+      security:
+        - placeholderAuth: []
      responses:
        "200":
          description: Client documents list.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDocuments"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /client/{id}/export:
    parameters:
@@ -267,6 +349,8 @@ paths:
        - ExportService
      summary: Trigger an export
      description: Initiates the export process.
+      security:
+        - placeholderAuth: []
      requestBody:
        description: The export requirements.
        required: true
@@ -277,12 +361,17 @@ paths:
      responses:
        "201":
          description: Export triggered successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

  /export/{id}:
    parameters:
@@ -293,15 +382,22 @@ paths:
        - ExportService
      summary: Check export state.
      description: Checks the current state of an export.
+      security:
+        - placeholderAuth: []
      responses:
        "200":
          description: Export has been completed.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportDetails"
        "400":
          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"

 components:
  parameters:
@@ -329,44 +425,77 @@ components:
        $ref: "#/components/schemas/QueryID"
      description: The ID of the query.

+  headers:
+    RateLimit:
+      schema:
+        type: string
+        pattern: "^[0-9]+;window=[0-9]+$"
+        maxLength: 32
+      description: Rate limit information in format "limit;window=time-window"
+      example: "100;window=60"
+
+  securitySchemes:
+    placeholderAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: "Placeholder security scheme for future implementation"
+
  responses:
    InvalidRequest:
      description: Invalid request body.
+      headers:
+        RateLimit:
+          $ref: "#/components/headers/RateLimit"
+
+    InternalError:
+      description: Internal server error.
+      headers:
+        RateLimit:
+          $ref: "#/components/headers/RateLimit"

  schemas:
    ClientID:
      type: string
      description: The client external id
      example: AAA
+      maxLength: 36
+      pattern: "^.+$"

    ClientUID:
      type: string
      format: uuid
      description: The client internal unique id
      example: 0195853c-8fdd-77cd-b36c-255241bddd33
+      maxLength: 36

    QueryID:
      type: string
      format: uuid
      description: The query id.
      example: 019580df-ef65-7676-8de9-94435a93337a
+      maxLength: 36

    DocumentID:
      type: string
      format: uuid
      description: The document id.
      example: 019580df-b3f8-7348-9ab1-1e55b3f18ed7
+      maxLength: 36

    ExportID:
      type: string
      format: uuid
      description: The export id.
      example: 019580de-4d51-713c-98ee-464e83811f13
+      maxLength: 36

    ClientName:
      type: string
      description: The client name
      example: AArete
+      maxLength: 256
+      pattern: "^.+$"

    ClientCanSync:
      type: boolean
@@ -382,6 +511,8 @@ components:
    QueryConfig:
      type: string
      description: Configuration for the query.
+      maxLength: 2048
+      pattern: '^\{.+\}$'

    Query:
      description: A logic unit of execution.
@@ -411,6 +542,7 @@ components:
      properties:
        queries:
          type: array
+          maxItems: 512
          items:
            $ref: "#/components/schemas/Query"
          description: List of queries.
@@ -432,6 +564,7 @@ components:

    RequiredQueryIDs:
      type: array
+      maxItems: 256
      items:
        $ref: "#/components/schemas/QueryID"
      description: List of required query IDs.
@@ -466,6 +599,8 @@ components:
        value:
          type: string
          description: Result of the query test.
+          pattern: "^.+$"
+          maxLength: 2048
      required:
        - value

@@ -516,6 +651,7 @@ components:
    ListDocuments:
      type: array
      description: The documents in the client.
+      maxItems: 256
      items:
        $ref: "#/components/schemas/Document"

@@ -528,9 +664,13 @@ components:
        bucket:
          type: string
          description: The bucket containing the document
+          maxLength: 256
+          pattern: "^.+$"
        key:
          type: string
          description: The path to the document
+          maxLength: 2048
+          pattern: "^.+/.+$"
      required:
        - id
        - bucket
@@ -565,17 +705,22 @@ components:
          type: string
          format: uuid
          description: Unique identifier for entity.
+          maxLength: 36
      required:
        - id

    CodeVersion:
      type: integer
      format: int64
+      minimum: 1
+      maximum: 9223372036854775808
      description: The desired code version.

    Version:
      type: integer
      format: int32
+      minimum: 0
+      maximum: 2147483647
      description: The desired version.

    Collector:
@@ -604,6 +749,7 @@ components:

    CollectorFields:
      type: array
+      maxItems: 256
      description: The fields in the collector.
      items:
        $ref: "#/components/schemas/CollectorField"
@@ -623,6 +769,8 @@ components:

    CollectorFieldName:
      type: string
+      pattern: "^[a-zA-Z]+$"
+      maxLength: 256
      description: The output field name.

    CollectorField:
@@ -646,12 +794,17 @@ components:
          properties:
            start_date:
              type: string
+              format: date-time
+              maxLength: 32
              description: This first date of ingestion.
            end_date:
              type: string
+              format: date-time
+              maxLength: 32
              description: The last date of ingestion.
        field_filters:
          type: array
+          maxItems: 256
          description: Filter the scope based on field output values.
          items:
            $ref: "#/components/schemas/FieldFilter"
@@ -667,8 +820,11 @@ components:
        values:
          type: array
          description: The values useful to the filter.
+          maxItems: 100
          items:
            type: string
+            pattern: "^.+$"
+            maxLength: 256
      description: Filtering a column
      required:
        - field_name
@@ -706,8 +862,9 @@ components:
        output_location:
          type: string
          description: The location in which the export zip file will be found.
-          example: |
-            s3://{bucket_name}/{external_client_id}/yyyymmdd/{export_id}.csv
+          example: s3://abc/AA/20250213/019587ac-073b-7098-8426-bad970f8c974.csv
+          maxLength: 2048
+          pattern: '^s3://.+/.+/[0-9]{8}/.+\.csv$'
      description: Payload for export trigger response.
      required:
        - client_id