Updating docs

docs/openapi/admin-api.yaml

@@ -1,20 +1,62 @@
 openapi: 3.1.0
 info:
-  version: 0.0.0.0.1
-  title: Dark Alley Admin
+  version: 1.0-RC
+  title: DA Admin API
   license:
     name: Apache 2.0
     url: http://www.apache.org/licenses/LICENSE-2.0.html
   x-logo:
-    url: https://raw.githubusercontent.com/auniverseaway/da-admin/main/docs/openapi/img/da-logo.png
+    url: http://127.0.0.1:8080/docs/openapi/img/da-logo.png
   description: |
-    Dark Alley Admin is used to manage Dark Alley content repositories.
+    DA Admin API is used to manage Document Authoring content repositories.
 
 servers:
-  - url: https://admin.da.live
+  - url: 'https://admin.da.live'
+
+components:
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - bearer: []
+
+tags:
+  - name: Source
+    description: |
+      The `source` API allows you to work directly with your content sources (Docs, Sheets, Media).
+  - name: Copy
+    description: |
+      The `copy` API allows you to copy a **directory** or **source**.
+  - name: Move
+    description: |
+      The `move` API allows you to move a **directory** or **source**.
+  - name: Version
+    description: |
+      The `versionsource` and `versionlist` APIs allow you to work with versions of source documents and sheets.
+  - name: List
+    description: |
+      The `list` API will list children of a directory.
+  - name: Config
+    description: |
+      The `config` API will allow you to associate sheet-formatted configurations with orgs, sites, directories, documents, and sheets.
+
 paths:
-  /source/{owner}/{path}:
+  /source/{org}/{repo}/{path}:
     $ref: "./source-api.yaml#/source"
-  /list/{owner}/{path}:
+  /copy/{org}/{repo}/{path}:
+    $ref: "./copy-api.yaml#/source"
+  /move/{org}/{repo}/{path}:
+    $ref: "./move-api.yaml#/source"
+  /list/{org}/{repo}/{path}:
     $ref: "./list-api.yaml#/list"
-
+  /versionsource/{org}/{repo}/{guid}:
+    $ref: "./version-api.yaml#/get"
+  /versionsource/{org}/{repo}/{path}:
+    $ref: "./version-api.yaml#/post"
+  /versionlist/{org}/{repo}/{path}:
+    $ref: "./version-api.yaml#/list"
+  /config/{org}/{repo}/{path}:
+    $ref: "./config-api.yaml#/source"

docs/openapi/config-api.yaml

@@ -0,0 +1,47 @@
+source:
+  get:
+    operationId: getConfig
+    tags:
+      - Config
+    summary: Config
+    description: Get a config for an org, repo, or source.
+    parameters:
+      - $ref: "./parameters.yaml#/pathParam"
+    responses:
+      '200':
+        $ref: "./responses.yaml#/200"
+      '400':
+        $ref: "./responses.yaml#/400"
+      '404':
+        $ref: "./responses.yaml#/404"
+  post:
+    operationId: createConfig
+    tags:
+      - Config
+    summary: New config
+    description: |
+      Create a config for an org, repo, or source.
+
+    parameters:
+      - $ref: "./parameters.yaml#/pathParam"
+    requestBody:
+      content:
+        multipart/form-data:
+          schema:
+            $ref: './schemas.yaml#/source'
+          examples:
+            json:
+              $ref: "./payloads.yaml#/copySourceForm"
+        # application/json:
+        #   schema:
+        #     $ref: './schemas.yaml#/jsonSource'
+        #   examples:
+        #     json:
+        #       $ref: "./payloads.yaml#/putSourceJson"
+    responses:
+      '201':
+        $ref: "./responses.yaml#/201"
+      '400':
+        $ref: "./responses.yaml#/400"
+      '500':
+        $ref: "./responses.yaml#/500"

docs/openapi/copy-api.yaml

@@ -0,0 +1,30 @@
+source:
+  post:
+    operationId: copySource
+    tags:
+      - Copy
+    summary: Copy source content
+    description: |
+      Copy a content source within an organization.
+    parameters:
+      - $ref: "./parameters.yaml#/orgParam"
+      - $ref: "./parameters.yaml#/repoParam"
+      - $ref: "./parameters.yaml#/pathParam"
+      - $ref: "./parameters.yaml#/extParam"
+    requestBody:
+      content:
+        multipart/form-data:
+          schema:
+            $ref: './schemas.yaml#/copy/source'
+          examples:
+            multipart:
+              $ref: "./payloads.yaml#/copySourceForm"
+    responses:
+      '204':
+        $ref: "./responses.yaml#/204"
+      '400':
+        $ref: "./responses.yaml#/400"
+      '401':
+        $ref: "./responses.yaml#/401"
+      '500':
+        $ref: "./responses.yaml#/500"

docs/openapi/list-api.yaml

@@ -3,14 +3,15 @@ list:
     operationId: listDetails
     tags:
       - List
-    summary: List sources - WIP
-    description: Returns a list of sources.
+    summary: List sources
+    description: Returns a list of sources from an organization.
     parameters:
-      - $ref: "./parameters.yaml#/daOwnerParam"
+      - $ref: "./parameters.yaml#/orgParam"
+      - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
     responses:
       '200':
-        $ref: "./responses.yaml#/200-list"
+        $ref: "./responses.yaml#/list/200"
       '400':
         $ref: "./responses.yaml#/400"
       '404':

docs/openapi/move-api.yaml

@@ -0,0 +1,30 @@
+source:
+  post:
+    operationId: moveSource
+    tags:
+      - Move
+    summary: Move source content
+    description: |
+      Move a content source within an organization.
+    parameters:
+      - $ref: "./parameters.yaml#/orgParam"
+      - $ref: "./parameters.yaml#/repoParam"
+      - $ref: "./parameters.yaml#/pathParam"
+      - $ref: "./parameters.yaml#/extParam"
+    requestBody:
+      content:
+        multipart/form-data:
+          schema:
+            $ref: './schemas.yaml#/move/source'
+          examples:
+            multipart:
+              $ref: "./payloads.yaml#/copySourceForm"
+    responses:
+      '204':
+        $ref: "./responses.yaml#/204"
+      '400':
+        $ref: "./responses.yaml#/400"
+      '401':
+        $ref: "./responses.yaml#/401"
+      '500':
+        $ref: "./responses.yaml#/500"

docs/openapi/parameters.yaml

@@ -1,7 +1,7 @@
-ownerParam:
-  name: owner
+orgParam:
+  name: org
   in: path
-  description: Repository owner.
+  description: The organization.
   required: true
   schema:
     type: string
@@ -19,24 +19,31 @@ refParam:
   required: true
   schema:
     type: string
-daOwnerParam:
-  name: owner
+pathParam:
+  name: path
   in: path
-  description: Name of the source owner.
+  description: Path to the source content.
   required: true
   schema:
     type: string
-pathParam:
-  name: path
+guidParam:
+  name: guid
   in: path
-  description: Path to the source content.
+  description: GUID of the version source.
   required: true
   schema:
     type: string
-headerParam:
-  name: x-da-metadata
-  in: header
+extReqParam:
+  name: ext
+  in: path
+  description: The source content file extension.
+  required: true
+  schema:
+    type: string
+extParam:
+  name: ext
+  in: path
+  description: The source content file extension.
+  required: false
   schema:
     type: string
-    example: '{"aemOrigin":"https://main--blog--adobecom.hlx.page"}'
-  description: Value to correlate API requests across systems.

docs/openapi/payloads.yaml

@@ -6,12 +6,7 @@ putSourceJson:
       readyForLoc: true
       lastRollout: 'Wed, 29 Nov 2023 01:20:40 GMT'
       timesAskedWhyNoNesting: 492
-putSourceForm:
-  summary: Override site details
+copySourceForm:
+  summary:
   value: |
-    data: <binary>
-    props: `{
-        "aemOrigin":"https://main--blog--adobecom.hlx.page",
-        "readForLoc": true,
-        "lastRollout": "Wed, 29 Nov 2023 01:20:40 GMT"
-      }`
+    destination: '/aemsites/geometrixx/path/to/file.html'