Add draft OpenAPI doc for user management

user-management.yaml

@@ -0,0 +1,195 @@
+openapi: 3.1.1
+
+info:
+  title: User management of OpenLEADR-rs
+  version: dev
+  description: This is a preliminary documentation of the HTTP APIs exposed for user management
+
+paths:
+  /auth/token:
+    post:
+      description: |
+        Authentication can happen either over HTTP basic auth,
+        or in the client_id/client_secret fields in the body
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                grant_type:
+                  required: true
+                  type: string
+                client_id:
+                  type: string
+                client_secret:
+                  type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  access_token:
+                    type: string
+                  token_type:
+                    type: string
+                  expires_in:
+                    type: integer
+                    format: uint64
+  /users:
+    get:
+      description: Get all users
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/user_details'
+    post:
+      description: Create a new user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/user_details'
+  /users/{user_id}:
+    parameters:
+      - name: user_id
+        in: path
+        description: user ID
+        required: true
+        schema:
+          type: string
+    get:
+      description: Get specific user
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/user_details'
+
+    put:
+      description: Edit user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/user_details'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/user_details'
+    delete:
+      description: Delete a user
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/user_details'
+    post:
+      description: Add a new credential / secret pair to a user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                client_id:
+                  type: string
+                client_secret:
+                  type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/user_details'
+
+  /users/{user_id}/{client_id}:
+    parameters:
+      - name: user_id
+        in: path
+        description: user ID
+        required: true
+        schema:
+          type: string
+      - name: client_id
+        in: path
+        description: client ID
+        required: true
+        schema:
+          type: string
+    delete:
+      description: Delete a client ID with its corresponding secret
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/user_details'
+
+components:
+  schemas:
+    user_details:
+      type: object
+      required:
+        - id
+        - reference
+        - description
+        - roles
+        - client_ids
+        - created
+        - modified
+      properties:
+        id:
+          readOnly: true
+          type: string
+        reference:
+          type: string
+        description:
+          type: string
+        roles:
+          type: array
+          items: 
+            $ref: '#/components/schemas/auth_role'
+        client_ids:
+          readOnly: true
+          type: array
+          items: string
+        created:
+          readOnly: true
+          type: string
+          format: date-time
+        modified:
+          readOnly: true
+          type: string
+          format: date-time
+    auth_role:
+      type: object
+      description: |
+        A auth role always contains the `role` property,
+        and the `VEN` and `Business` role additionally have an `id` property with the VEN or Business ID, respectively.
+      required:
+        - role
+      properties:
+        role:
+          type: string
+          enum: [UserManager, VenManager, Business, AnyBusiness, VEN]
+        id:
+          type: string
+