ENH: Document insertion of entities

src/doc/development/api/xml/caosdb_openapi.yaml

@@ -105,7 +105,66 @@ paths:
                     id: 101
                   - name: "Result 2"
                     id: 102
-                  
+    post:
+      operationId: insertEntity
+      summary: Insert one or more entities
+      description: Upload one or several entities to be inserted on the server
+      requestBody:
+        required: true
+        description: The entity or the entities to be inserted
+        content:
+          application/xml:
+            schema:
+              $ref: "#/components/schemas/Request"
+            example:
+              entity:
+                - name: "MyNewRecord"
+                  description: "Test"
+                  Parent:
+                    - name: "ParentType"
+                      id: 123
+                  Property:
+                    - name: "SomeProperty"
+                      id: 124
+                      datatype: "INTEGER"
+                      value: 3
+      responses:
+        '200':
+          description: The inserted entity object(s) with information added by the server
+          content:
+            application/xml:
+              schema:
+                $ref: "#/components/schemas/Response"
+              example:
+                username: admin
+                realm: PAM
+                srid: "some-srid"
+                timestamp: 12345
+                baseuri: "https://demo.indiscale.com"
+                count: 1
+                UserInfo:
+                  username: admin
+                  realm: PAM
+                  roles:
+                    - administration
+                entity:
+                  id: 365
+                  name: "MyNewRecord"
+                  description: "Test"
+                  Version:
+                    id: "some-version-string"
+                    head: true
+                  Permissions:
+                    - name: "RETRIEVE:ENTITY"
+                    - name: "RETRIEVE:ACL"
+                  Parent:
+                    - name: "ParentType"
+                      id: 123
+                  Property:
+                    - name: "SomeProperty"
+                      id: 124
+                      datatype: "INTEGER"
+                      value: 3                
 components:
   schemas:
     Response:
@@ -138,6 +197,14 @@ components:
             $ref: "#/components/schemas/entity"
         Query:
           $ref: "#/components/schemas/Query"
+    Request:
+      type: object
+      description: Request to be inserted or updated
+      properties:
+        entity:
+          type: array
+          items:
+            $ref: "#/components/schemas/entity"
     entity:
       type: object
       properties: