Improve API docs

openapi/components/schemas/company_user.yaml

@@ -1,27 +1,32 @@
     CompanyUser:
       properties:
         permissions:
-          description: 'The company user permissions'
+          description: 'The user permissionsfor this company in a comma separated list'
           type: string
-          example: '[create_invoice]'
+          example: 'create_invoice,create_client,view_client'
         settings:
-          description: 'Settings that are used for the frontend applications to store user preferences / metadata'
+          description: 'Settings that are used for the flutter applications to store user preferences / metadata'
           type: object
+          readOnly: true
         react_settings:
           description: 'Dedicated settings object for the react web application'
           type: object
+          readOnly: true
         is_owner:
           description: 'Determines whether the user owns this company'
           type: boolean
           example: true
+          readOnly: true
         is_admin:
           description: 'Determines whether the user is the admin of this company'
           type: boolean
           example: true
+          readOnly: true
         is_locked:
           description: 'Determines whether the users access to this company has been locked'
           type: boolean
           example: true
+          readOnly: true
         updated_at:
           description: 'The last time the record was modified, format Unix Timestamp'
           type: integer

openapi/info.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  title: 'Invoice Ninja API Reference - Where self host invoicing lives.'
+  title: 'Invoice Ninja API Reference.'
   description: |
         ---
         <br>
@@ -15,7 +15,7 @@ info:
   license:
     name: 'Elastic License'
     url: 'https://www.elastic.co/licensing/elastic-license'
-  version: 5.5.70
+  version: 5.8.34
 servers:
   -
     url: 'https://demo.invoiceninja.com'

openapi/paths.yaml

@@ -89,7 +89,14 @@ paths:
       tags:
         - login
       summary: "Attempts authentication"
-      description: "Returns a CompanyUser object on success"
+      description: |
+        After authenticating with the API, the returned object is a CompanyUser object which is a bridge linking the user to the company. 
+
+        The company user object itself contains the users permissions (admin/owner or fine grained permissions) You will most likely want to 
+        also include in the response of this object both the company and the user object, this can be done by using the include parameter.
+
+        /api/v1/login?include=company,user
+
       operationId: postLogin
       parameters:
         - $ref: "#/components/parameters/X-API-SECRET"
@@ -109,10 +116,17 @@ paths:
                   description: "The users email address."
                   type: string
                   example: "demo@invoiceninja.com"
+                  required: true
                 password:
                   description: "The user password. Must meet minimum criteria ~ > 6 characters"
                   type: string
                   example: "Password0"
+                  required: true
+                one_time_password:
+                  description: "The one time password if 2FA is enabled"
+                  type: string
+                  example: "123456"
+                  required: false
               type: object
       responses:
         200:
@@ -127,13 +141,15 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Client"
+                $ref: "#/components/schemas/CompanyUser"
         401:
           $ref: "#/components/responses/401"
         403:
           $ref: "#/components/responses/403"
         422:
           $ref: "#/components/responses/422"
+        429:
+          $ref: "#/components/responses/429"
         5XX:
           description: 'Server error'
         default: