Improving API Docs

openapi/api-docs.yaml

@@ -28,7 +28,7 @@ paths:
       tags:
         - actvities
       summary: 'Gets a list of actvities'
-      description: 'Lists all activities'
+      description: 'Lists all activities related to this company'
       operationId: getActivities
       parameters:
         -
@@ -36,7 +36,7 @@ paths:
         -
           $ref: '#/components/parameters/X-Requested-With'
         -
-          $ref: '#/components/parameters/include'
+          $ref: '#/components/parameters/activity_include'
         -
           $ref: '#/components/parameters/index'
         -
@@ -86,6 +86,8 @@ paths:
           $ref: '#/components/parameters/X-API-TOKEN'
         -
           $ref: '#/components/parameters/X-Requested-With'
+        -
+          $ref: '#/components/parameters/activity_include'
         -
           name: activity_id
           in: path
@@ -1548,7 +1550,7 @@ paths:
         -
           name: rows
           in: query
-          description: 'The number of activities to return'
+          description: 'The chart'
           required: false
           schema:
             type: number
@@ -16312,9 +16314,9 @@ components:
           type: string
           example: '[create_invoice]'
         settings:
-          description: 'The company name'
+          description: 'Settings that are used for the frontend applications to store user preferences / metadata'
           type: object
-          example: 'The local shop'
+          example: 'json object'
         is_owner:
           description: 'Determines whether the user owns this company'
           type: boolean
@@ -16328,11 +16330,11 @@ components:
           type: boolean
           example: true
         updated_at:
-          description: 'The last time the record was modified'
+          description: 'The last time the record was modified, format Unix Timestamp'
           type: integer
           example: '1231232312321'
         deleted_at:
-          description: 'Timestamp when the user was archived'
+          description: 'Timestamp when the user was archived, format Unix Timestamp'
           type: integer
           example: '12312312321'
         account:
@@ -18660,19 +18662,12 @@ components:
           example: google
       type: object
     AuthenticationError:
+      type: object  
       properties:
         message:
           description: 'These credentials do not match our records'
           type: string
           example: 'These credentials do not match our records'
-        errors:
-          properties:
-            value:
-              type: array
-              items:
-                type: string
-          type: object
-      type: object  
     ValidationError:
       properties:
         message:
@@ -18938,6 +18933,53 @@ components:
       schema:
         type: string
         example: supersecretpassword
+    activity_include:
+      name: activity_include
+      in: query
+      description: Include child relations of the Activity object, format is comma separated. **Note** it is possible to chain multiple includes together, ie. include=account,token
+      required: false
+      schema:
+        type: string
+      examples:
+        history:
+          value: history
+          summary: include=history will include the history object in the response (This could include references to the backup HTML of the entity)
+        user:
+          value: user
+          summary: include=user will include the user object in the response
+        client:
+          value: client
+          summary: include=client will include the client object in the response
+        recurring_invoice:
+          value: recurring_invoice
+          summary: include=recurring_invoice will include the recurring_invoice object in the response
+        invoice:
+          value: invoice
+          summary: include=invoice will include the invoice object in the response
+        credit:
+          value: credit
+          summary: include=credit will include the credit object in the response
+        quote:
+          value: quote
+          summary: include=quote will include the quote object in the response
+        payment:
+          value: payment
+          summary: include=payment will include the payment object in the response
+        expense:
+          value: expense
+          summary: include=expense will include the expense object in the response           
+        vendor_contact:
+          value: vendor_contact
+          summary: include=vendor_contact will include the vendor_contact object in the response
+        vendor:
+          value: vendor
+          summary: include=vendor will include the vendor object in the response
+        purchase_order:
+          value: purchase_order
+          summary: include=purchase_order will include the purchase_order object in the response
+        task:
+          value: task
+          summary: include=task will include the task object in the response        
     login_include:
       name: login_include
       in: query

openapi/components/components.yaml

@@ -1432,9 +1432,9 @@ components:
           type: string
           example: '[create_invoice]'
         settings:
-          description: 'The company name'
+          description: 'Settings that are used for the frontend applications to store user preferences / metadata'
           type: object
-          example: 'The local shop'
+          example: 'json object'
         is_owner:
           description: 'Determines whether the user owns this company'
           type: boolean
@@ -1448,11 +1448,11 @@ components:
           type: boolean
           example: true
         updated_at:
-          description: 'The last time the record was modified'
+          description: 'The last time the record was modified, format Unix Timestamp'
           type: integer
           example: '1231232312321'
         deleted_at:
-          description: 'Timestamp when the user was archived'
+          description: 'Timestamp when the user was archived, format Unix Timestamp'
           type: integer
           example: '12312312321'
         account:
@@ -3780,19 +3780,12 @@ components:
           example: google
       type: object
     AuthenticationError:
+      type: object  
       properties:
         message:
           description: 'These credentials do not match our records'
           type: string
           example: 'These credentials do not match our records'
-        errors:
-          properties:
-            value:
-              type: array
-              items:
-                type: string
-          type: object
-      type: object  
     ValidationError:
       properties:
         message:
@@ -4058,6 +4051,53 @@ components:
       schema:
         type: string
         example: supersecretpassword
+    activity_include:
+      name: activity_include
+      in: query
+      description: Include child relations of the Activity object, format is comma separated. **Note** it is possible to chain multiple includes together, ie. include=account,token
+      required: false
+      schema:
+        type: string
+      examples:
+        history:
+          value: history
+          summary: include=history will include the history object in the response (This could include references to the backup HTML of the entity)
+        user:
+          value: user
+          summary: include=user will include the user object in the response
+        client:
+          value: client
+          summary: include=client will include the client object in the response
+        recurring_invoice:
+          value: recurring_invoice
+          summary: include=recurring_invoice will include the recurring_invoice object in the response
+        invoice:
+          value: invoice
+          summary: include=invoice will include the invoice object in the response
+        credit:
+          value: credit
+          summary: include=credit will include the credit object in the response
+        quote:
+          value: quote
+          summary: include=quote will include the quote object in the response
+        payment:
+          value: payment
+          summary: include=payment will include the payment object in the response
+        expense:
+          value: expense
+          summary: include=expense will include the expense object in the response           
+        vendor_contact:
+          value: vendor_contact
+          summary: include=vendor_contact will include the vendor_contact object in the response
+        vendor:
+          value: vendor
+          summary: include=vendor will include the vendor object in the response
+        purchase_order:
+          value: purchase_order
+          summary: include=purchase_order will include the purchase_order object in the response
+        task:
+          value: task
+          summary: include=task will include the task object in the response        
     login_include:
       name: login_include
       in: query

openapi/paths/paths.yaml

@@ -4,7 +4,7 @@ paths:
       tags:
         - actvities
       summary: 'Gets a list of actvities'
-      description: 'Lists all activities'
+      description: 'Lists all activities related to this company'
       operationId: getActivities
       parameters:
         -
@@ -12,7 +12,7 @@ paths:
         -
           $ref: '#/components/parameters/X-Requested-With'
         -
-          $ref: '#/components/parameters/include'
+          $ref: '#/components/parameters/activity_include'
         -
           $ref: '#/components/parameters/index'
         -
@@ -62,6 +62,8 @@ paths:
           $ref: '#/components/parameters/X-API-TOKEN'
         -
           $ref: '#/components/parameters/X-Requested-With'
+        -
+          $ref: '#/components/parameters/activity_include'
         -
           name: activity_id
           in: path
@@ -1524,7 +1526,7 @@ paths:
         -
           name: rows
           in: query
-          description: 'The number of activities to return'
+          description: 'The chart'
           required: false
           schema:
             type: number