ATS-17: Add private OpenAPI spec for Alfresco Transform Engines API

- first draft for /transform REST API (including basic T-Request / T-Reply model definitions)

docs/alfresco-transformer.yaml

@@ -0,0 +1,191 @@
+swagger: '2.0'
+info:
+  description: |
+    **Alfresco Transform Engines REST API**
+
+    Transform Request & Response API to allow a source file to be transformed into a 
+    target file, given a set of transform options. 
+    
+    The new JSON-based Transform Engines API is used by the Alfresco Transform Service (ATS).
+    ATS provides an independently-scalable transform service, initially used by ACS 
+    Content Repository, as part of the overall Alfresco Digital Business Platform (DBP).
+    
+    Note: Each kind of Transform Engine implements this Transform Engines API, including:
+    
+    * ImageMagick
+    * LibreOffice
+    * PDF Renderer
+    * Tika
+    
+    In the future, this Transform Engines API may form the basis for adding custom Transform Engines.
+    
+  version: '1'
+  title: Alfresco Transform Engines REST API
+basePath: /alfresco/api/-default-/private/transformer/versions/1
+tags:
+  - name: Transform
+    description: Transform Engine Request / Respone
+paths:
+  '/transform':
+    post:
+      x-alfresco-since: "2.0"
+      tags:
+        - Transform
+      summary: Transform Engines API
+      description: |
+        **Note:** available with Alfresco Transform Engines 2.0 and newer versions.
+        
+        This endpoint supports both JSON and multipart/form-data.
+        
+        **Using JSON (application/json -> application/json)**
+        
+        The JSON API relies on the source and target files to be stored and retrieved via 
+        the Shared File Store. This is used within the Alfresco Transform Service. 
+        The ACS Content Repository 6.1 (or higher) provides the option to offload 
+        supported transformations to the Alfresco Transform Service.
+        
+        Here's a pseudo-example transform request:
+        
+        ```JSON
+        {
+          "schema": 1,
+          "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
+          "clientData": "opaque-client-specific-data-123xyz",
+          "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04",
+          "sourceSize": 32713,
+          "sourceMediaType: "image/jpeg",
+          "sourceExtension": "jpeg",
+          "targetMediaType: "image/png",
+          "targetExtension": "png",
+          "transformRequestOptions": {
+            "resizeWidth": "25",
+            "resizePercentage": "true",
+            "maintainAspectRatio": "true"
+          }
+        }
+        ```
+        
+        Here's an pseudo-example response of a successful transform:
+        
+        ```JSON
+        {
+          "schema": 1,
+          "status": 201
+          "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
+          "clientData": "opaque-client-specific-data-123xyz",
+          "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04",
+          "targetReference": "5bc81e48-e17a-4727-bd1c-3a279aa6b421"
+        }
+        ```
+        
+        Here's an pseudo-example response of a successful transform:
+        
+        ```JSON
+        {
+          "schema": 1,
+          "errorDetails": "Lorem ipsum dolor sit amet, ..."
+          "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
+          "clientData": "opaque-client-specific-data-123xyz",
+          "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04"
+        }
+        ```
+        
+        **Using Multipart (multipart/form-data -> application/octet-stream)**
+        
+        The Multipart API remains for backwards compatibility (eg. ACS 6.0). It requires 
+        the source file to be uploaded via multipart/form-data (along with transformation 
+        options). The target file is returned as a binary response (application/octet-steam).
+        
+      operationId: transformOperation
+      parameters:
+        - in: body
+          name: transformRequest
+          description: The Transform Request including source reference and transform options 
+          required: true
+          schema:
+            $ref: '#/definitions/transformRequest'      
+      consumes:
+        - application/json
+        - multipart/form-data
+      produces:
+        - application/json
+        - application/octet-stream
+      responses:
+        '201':
+          description: Successful response
+          schema:
+            $ref: '#/definitions/transformReply'
+        default:
+          description: Unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+definitions:
+  Error:
+    type: object
+    required:
+      - error
+    properties:
+      error:
+        type: object
+        required:
+          - statusCode
+          - briefSummary
+          - stackTrace
+          - descriptionURL
+        properties:
+          errorKey:
+            type: string
+          statusCode:
+            type: integer
+            format: int32
+          briefSummary:
+            type: string
+          stackTrace:
+            type: string
+          descriptionURL:
+            type: string
+          logId:
+            type: string
+  transformRequest:
+    type: object
+    properties:
+      requestId:
+        type: string
+      sourceReference:
+        type: string
+      sourceMediaType:
+        type: string
+      sourceSize:
+        type: integer
+        format: int64
+      sourceExtension:
+        type: string
+      targetMediaType:
+        type: string
+      targetExtension:
+        type: string
+      clientData:
+        type: string
+      schema:
+        type: integer
+      transformRequestOptions:
+        type: object
+        additionalProperties:
+          type: string        
+  transformReply:
+    type: object
+    properties:
+      status:
+        type: integer
+      requestId:
+        type: string
+      sourceReference:
+        type: string
+      targetReference:
+        type: string
+      clientData:
+        type: string
+      schema:
+        type: integer
+      errorDetails:
+        type: string