ADD Doc API keys endpoints to documentation

README.md

@@ -6,7 +6,7 @@ Repository for Grist documentation and tutorials.
 
 The public site is at <https://support.getgrist.com/>, served using GitHub Pages.
 
-The content is hosted at <https://github.com/dsagal/grist-help/>. On changes to master (such as
+The content is hosted at <https://github.com/gristlabs/grist-help/>. On changes to master (such as
 when a pull request is merged), the public site gets automatically republished.
 
 Previews of pull requests are automatically built by Netlify, and made available at URLs such as
@@ -15,6 +15,8 @@ Conversation tab.
 
 ## Setting up local environment
 
+N.B.: Python 3.12 isn't supported yet. Please, use Python 3.10 or 3.11 instead.
+
 ``` sh
 # initiate a python virtual environment
 python3 -m venv env
@@ -92,7 +94,7 @@ Once you're done, add the results to the main documentation with:
 To update `help/en/docs/functions.md` from the documentation comments in Grist, run:
 
 ```
-./build-functions.sh <path-to-grist-checkout>
+./build-functions.sh <path-to-grist-core-checkout>
 ```
 
 It replaces content between `BEGIN mkpydocs`/`END mkpydocs` markers in `help/en/docs/functions.md`. You
@@ -103,7 +105,7 @@ can edit text outside of those markers directly.
 To update `help/en/docs/code` from the documentation comments in Grist, run:
 
 ```
-./build-plugin-api.sh <path-to-grist-checkout>
+./build-plugin-api.sh <path-to-grist-core-checkout>
 ```
 
 You need to first run `yarn install` in your Grist checkout directory.

api/grist.yml

@@ -929,7 +929,95 @@ paths:
       responses:
         200:
           description: Success
-
+  /docs/{docId}/apikey:
+    post:
+      operationId: "createDocApiKey"
+      tags:
+        - document API key
+      summary: "Create a document API key"
+      parameters:
+        - $ref: '#/components/parameters/docIdPathParam'
+      requestBody:
+        description: >
+          A Share object.
+          The linkId must be unique for the document.
+          In options the apiKey flag set to true is mandatory.
+          In options access can be set to editors or viewers.
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateDocApiKey"
+        required: true
+      responses:
+        200:
+          description: Success
+          content:
+  /docs/{docId}/apikey/{linkId}:
+    get:
+      operationId: "readDocApiKey"
+      tags:
+        - document API key
+      summary: "Read a document API key"
+      parameters:
+        - $ref: '#/components/parameters/docIdPathParam'
+        - $ref: '#/components/parameters/linkIdPathParam'
+      responses:
+        200:
+          description: Success
+    patch:
+      operationId: "updateDocApiKey"
+      tags:
+        - document API key
+      summary: "Update a document API key"
+      parameters:
+        - $ref: '#/components/parameters/docIdPathParam'
+        - $ref: '#/components/parameters/linkIdPathParam'
+      requestBody:
+        description: >
+          A Share object.
+          The linkId must be unique for the document.
+          In options the apiKey flag set to true is mandatory.
+          In options access can be set to editors or viewers.
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateDocApiKey"
+        required: true
+      responses:
+        200:
+          description: Success
+    delete:
+      operationId: "deleteDocApiKey"
+      tags:
+        - document API key
+      summary: "Delete a document API key"
+      parameters:
+        - $ref: '#/components/parameters/docIdPathParam'
+        - $ref: '#/components/parameters/linkIdPathParam'
+      responses:
+        200:
+          description: Success
+  /docs/{docId}/apikeys:
+    get:
+      operationId: "readDocApiKeys"
+      tags:
+        - document API key
+      summary: "Read all API keys of a document"
+      parameters:
+        - $ref: '#/components/parameters/docIdPathParam'
+      responses:
+        200:
+          description: Success
+    delete:
+      operationId: "deleteDocApiKeys"
+      tags:
+        - document API key
+      summary: "Delete all API keys of a document"
+      parameters:
+        - $ref: '#/components/parameters/docIdPathParam'
+      responses:
+        200:
+          description: Success
   /docs/{docId}/webhooks:
     get:
       tags:
@@ -1696,7 +1784,41 @@ components:
               - id: popularity
                 fields:
                   label: "Popularity ❤"
-
+    DocApiKeyOptions:
+      type: object
+      properties:
+        apikey:
+          type: boolean
+          enum: true
+          example: true
+        access:
+          type: string
+          enum:
+            -editors
+            -viewers
+          example: editors
+    CreateDocApiKey:
+      type: object
+      properties:
+        docId:
+          type: string
+          example: XXXXXXXXXXX
+        linkId:
+          type: string
+          example: YYYYYYYYYYY
+        options:
+          $ref: "#/components/schemas/DocApiKeyOptions"
+    UpdateDocApiKey:
+      type: object
+      properties:
+        docId:
+          type: string
+          example: XXXXXXXXXXX
+        linkId:
+          type: string
+          example: YYYYYYYYYYY
+        options:
+          $ref: "#/components/schemas/DocApiKeyOptions"
     ColumnsList:
       type: object
       properties:
@@ -1814,7 +1936,19 @@ components:
         type:
           type: string
           description: "Column type, by default Any. Ref, RefList and DateTime types requires a postfix, e.g. <code>DateTime:America/New_York</code>, <code>Ref:Users</code>"
-          enum: [Any, Text, Numeric, Int, Bool, Date, DateTime:<timezone>, Choice, ChoiceList, Ref:<tableId>, RefList:<tableId>, Attachments]
+          enum:
+            - Any
+            - Text
+            - Numeric
+            - Int
+            - Bool
+            - Date
+            - DateTime:<timezone>
+            - Choice
+            - ChoiceList
+            - Ref:<tableId>
+            - RefList:<tableId>
+            - Attachments
         label:
           type: string
           description: Column label.
@@ -2163,6 +2297,13 @@ components:
         type: integer
       description: A user id
       required: true
+    linkIdPathParam:
+      in: path
+      name: linkId
+      schema:
+        type: string
+      description: A string id (UUID)
+      required: true
     noparseQueryParam:
       in: query
       name: noparse