Cutlery/invoiceninja
1
0
Fork 0
mirror of https://github.com/invoiceninja/invoiceninja.git synced 2025-06-01 02:44:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

Completing OpenAPI documentation for clients

Browse Source
This commit is contained in:
David Bomba 2023-04-30 00:03:25 +10:00
parent 4e8d1a58f2
commit f74d118994
4 changed files with 399 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
openapi/api-docs.yaml
View File

@ -9644,6 +9644,13 @@ paths:
- $ref: "#/components/parameters/X-API-TOKEN" - $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With" - $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include" - $ref: "#/components/parameters/include"
requestBody:
description: Product object that needs to be added to the company
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductRequest'
responses: responses:
200: 200:
description: "Returns the saved product object" description: "Returns the saved product object"
@ -16595,6 +16602,166 @@ components:
type: string type: string
example: 'Bob Smith' example: 'Bob Smith'
type: object type: object
ProductRequest:
type: object
properties:
id:
type: string
description: 'The hashed product ID.'
example: eP01N
readOnly: true
assigned_user_id:
type: string
description: 'The hashed ID of the user assigned to this product.'
example: pR0j3
required: false
project_id:
type: string
description: 'The hashed ID of the project that this product is associated with.'
example: pR0j3
required: false
vendor_id:
type: string
description: 'The hashed ID of the vendor that this product is associated with.'
example: pR0j3
required: false
custom_value1:
type: string
description: 'Custom value field 1.'
example: 'Custom value 1'
required: false
custom_value2:
type: string
description: 'Custom value field 2.'
example: 'Custom value 2'
required: false
custom_value3:
type: string
description: 'Custom value field 3.'
example: 'Custom value 3'
required: false
custom_value4:
type: string
description: 'Custom value field 4.'
example: 'Custom value 4'
required: false
product_key:
type: string
description: 'The product key.'
example: '1234'
required: false
notes:
type: string
description: 'Notes about the product.'
example: 'These are some notes about the product.'
required: false
cost:
type: number
format: double
description: 'The cost of the product.'
example: 10.0
required: false
price:
type: number
format: double
description: 'The price of the product.'
example: 20.0
required: false
quantity:
type: number
format: double
description: 'The quantity of the product.'
example: 5.0
required: false
default: 1
tax_name1:
type: string
description: 'The name of tax 1.'
example: 'Tax 1'
required: false
tax_rate1:
type: number
format: double
description: 'The rate of tax 1.'
example: 10.0
required: false
tax_name2:
type: string
description: 'The name of tax 2.'
example: 'Tax 2'
required: false
tax_rate2:
type: number
format: double
description: 'The rate of tax 2.'
example: 5.0
required: false
tax_name3:
type: string
description: 'The name of tax 3.'
example: 'Tax 3'
required: false
tax_rate3:
type: number
format: double
description: 'The rate of tax 3.'
example: 0.0
required: false
in_stock_quantity:
type: integer
format: int32
description: |
The quantity of the product that is currently in stock.
**note** this field is not mutable without passing an extra query parameter which will allow modification of this value.
The query parameter ?update_in_stock_quantity=true **MUST** be passed if you wish to update this value manually.
default: 0
required: false
stock_notification:
type: boolean
description: Indicates whether stock notifications are enabled for this product
default: true
required: false
stock_notification_threshold:
type: integer
format: int32
description: The minimum quantity threshold for which stock notifications will be triggered
default: 0
required: false
max_quantity:
type: integer
format: int32
description: The maximum quantity that can be ordered for this product
required: false
product_image:
type: string
description: The URL of the product image
format: uri-reference
required: false
tax_id:
type: string
default: '1'
required: false
description: |
The tax category id for this product.'
The following constants are available (default = '1')
```
PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'
```
example: '1'
Error: Error:
properties: properties:
message: message:
@ -19112,14 +19279,17 @@ components:
type: string type: string
description: 'The hashed product ID.' description: 'The hashed product ID.'
example: eP01N example: eP01N
readOnly: true
company_id: company_id:
type: string type: string
description: 'The hashed ID of the company that owns this product.' description: 'The hashed ID of the company that owns this product.'
example: eP01N example: eP01N
readOnly: true
user_id: user_id:
type: string type: string
description: 'The hashed ID of the user that created this product.' description: 'The hashed ID of the user that created this product.'
example: n30m4 example: n30m4
readOnly: true
assigned_user_id: assigned_user_id:
type: string type: string
description: 'The hashed ID of the user assigned to this product.' description: 'The hashed ID of the user assigned to this product.'
@ -19158,17 +19328,17 @@ components:
example: 'These are some notes about the product.' example: 'These are some notes about the product.'
cost: cost:
type: number type: number
format: float format: double
description: 'The cost of the product.' description: 'The cost of the product.'
example: 10.0 example: 10.0
price: price:
type: number type: number
format: float format: double
description: 'The price of the product.' description: 'The price of the product.'
example: 20.0 example: 20.0
quantity: quantity:
type: number type: number
format: float format: double
description: 'The quantity of the product.' description: 'The quantity of the product.'
example: 5.0 example: 5.0
tax_name1: tax_name1:
@ -19177,7 +19347,7 @@ components:
example: 'Tax 1' example: 'Tax 1'
tax_rate1: tax_rate1:
type: number type: number
format: float format: double
description: 'The rate of tax 1.' description: 'The rate of tax 1.'
example: 10.0 example: 10.0
tax_name2: tax_name2:
@ -19186,7 +19356,7 @@ components:
example: 'Tax 2' example: 'Tax 2'
tax_rate2: tax_rate2:
type: number type: number
format: float format: double
description: 'The rate of tax 2.' description: 'The rate of tax 2.'
example: 5.0 example: 5.0
tax_name3: tax_name3:
@ -19195,7 +19365,7 @@ components:
example: 'Tax 3' example: 'Tax 3'
tax_rate3: tax_rate3:
type: number type: number
format: float format: double
description: 'The rate of tax 3.' description: 'The rate of tax 3.'
example: 0.0 example: 0.0
archived_at: archived_at:
@ -19203,46 +19373,66 @@ components:
format: timestamp format: timestamp
description: 'The timestamp when the product was archived.' description: 'The timestamp when the product was archived.'
example: '2022-03-18T15:00:00Z' example: '2022-03-18T15:00:00Z'
readOnly: true
created_at: created_at:
type: integer type: integer
format: timestamp format: timestamp
description: 'The timestamp when the product was created.' description: 'The timestamp when the product was created.'
example: '2022-03-18T15:00:00Z' example: '2022-03-18T15:00:00Z'
readOnly: true
updated_at: updated_at:
description: Timestamp description: Timestamp
type: integer type: integer
format: timestamp format: timestamp
example: '2022-03-18T12:34:56.789Z' example: '2022-03-18T12:34:56.789Z'
readOnly: true
is_deleted: is_deleted:
type: boolean type: boolean
description: 'Boolean flag determining if the product has been deleted' description: 'Boolean flag determining if the product has been deleted'
example: false example: false
readOnly: true
in_stock_quantity: in_stock_quantity:
type: integer type: integer
format: int32 format: int32
description: The quantity of the product that is currently in stock description: The quantity of the product that is currently in stock
default: 0 default: 0
stock_notification: stock_notification:
type: boolean type: boolean
description: Indicates whether stock notifications are enabled for this product description: Indicates whether stock notifications are enabled for this product
default: true default: true
stock_notification_threshold: stock_notification_threshold:
type: integer type: integer
format: int32 format: int32
description: The minimum quantity threshold for which stock notifications will be triggered description: The minimum quantity threshold for which stock notifications will be triggered
default: 0 default: 0
max_quantity: max_quantity:
type: integer type: integer
format: int32 format: int32
description: The maximum quantity that can be ordered for this product description: The maximum quantity that can be ordered for this product
product_image: product_image:
type: string type: string
description: The URL of the product image description: The URL of the product image
format: uri-reference format: uri-reference
tax_id:
type: string
default: '1'
description: |
The tax category id for this product.'
The following constants are available (default = '1')
```
PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'
```
example: '1'
Quote: Quote:
properties: properties:

43
openapi/components/schemas/product.yaml
View File

@ -5,14 +5,17 @@
type: string type: string
description: 'The hashed product ID.' description: 'The hashed product ID.'
example: eP01N example: eP01N
readOnly: true
company_id: company_id:
type: string type: string
description: 'The hashed ID of the company that owns this product.' description: 'The hashed ID of the company that owns this product.'
example: eP01N example: eP01N
readOnly: true
user_id: user_id:
type: string type: string
description: 'The hashed ID of the user that created this product.' description: 'The hashed ID of the user that created this product.'
example: n30m4 example: n30m4
readOnly: true
assigned_user_id: assigned_user_id:
type: string type: string
description: 'The hashed ID of the user assigned to this product.' description: 'The hashed ID of the user assigned to this product.'
@ -51,17 +54,17 @@
example: 'These are some notes about the product.' example: 'These are some notes about the product.'
cost: cost:
type: number type: number
format: float format: double
description: 'The cost of the product.' description: 'The cost of the product.'
example: 10.0 example: 10.0
price: price:
type: number type: number
format: float format: double
description: 'The price of the product.' description: 'The price of the product.'
example: 20.0 example: 20.0
quantity: quantity:
type: number type: number
format: float format: double
description: 'The quantity of the product.' description: 'The quantity of the product.'
example: 5.0 example: 5.0
tax_name1: tax_name1:
@ -70,7 +73,7 @@
example: 'Tax 1' example: 'Tax 1'
tax_rate1: tax_rate1:
type: number type: number
format: float format: double
description: 'The rate of tax 1.' description: 'The rate of tax 1.'
example: 10.0 example: 10.0
tax_name2: tax_name2:
@ -79,7 +82,7 @@
example: 'Tax 2' example: 'Tax 2'
tax_rate2: tax_rate2:
type: number type: number
format: float format: double
description: 'The rate of tax 2.' description: 'The rate of tax 2.'
example: 5.0 example: 5.0
tax_name3: tax_name3:
@ -88,7 +91,7 @@
example: 'Tax 3' example: 'Tax 3'
tax_rate3: tax_rate3:
type: number type: number
format: float format: double
description: 'The rate of tax 3.' description: 'The rate of tax 3.'
example: 0.0 example: 0.0
archived_at: archived_at:
@ -96,43 +99,63 @@
format: timestamp format: timestamp
description: 'The timestamp when the product was archived.' description: 'The timestamp when the product was archived.'
example: '2022-03-18T15:00:00Z' example: '2022-03-18T15:00:00Z'
readOnly: true
created_at: created_at:
type: integer type: integer
format: timestamp format: timestamp
description: 'The timestamp when the product was created.' description: 'The timestamp when the product was created.'
example: '2022-03-18T15:00:00Z' example: '2022-03-18T15:00:00Z'
readOnly: true
updated_at: updated_at:
description: Timestamp description: Timestamp
type: integer type: integer
format: timestamp format: timestamp
example: '2022-03-18T12:34:56.789Z' example: '2022-03-18T12:34:56.789Z'
readOnly: true
is_deleted: is_deleted:
type: boolean type: boolean
description: 'Boolean flag determining if the product has been deleted' description: 'Boolean flag determining if the product has been deleted'
example: false example: false
readOnly: true
in_stock_quantity: in_stock_quantity:
type: integer type: integer
format: int32 format: int32
description: The quantity of the product that is currently in stock description: The quantity of the product that is currently in stock
default: 0 default: 0
stock_notification: stock_notification:
type: boolean type: boolean
description: Indicates whether stock notifications are enabled for this product description: Indicates whether stock notifications are enabled for this product
default: true default: true
stock_notification_threshold: stock_notification_threshold:
type: integer type: integer
format: int32 format: int32
description: The minimum quantity threshold for which stock notifications will be triggered description: The minimum quantity threshold for which stock notifications will be triggered
default: 0 default: 0
max_quantity: max_quantity:
type: integer type: integer
format: int32 format: int32
description: The maximum quantity that can be ordered for this product description: The maximum quantity that can be ordered for this product
product_image: product_image:
type: string type: string
description: The URL of the product image description: The URL of the product image
format: uri-reference format: uri-reference
tax_id:
type: string
default: '1'
description: |
The tax category id for this product.'
The following constants are available (default = '1')
```
PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'
```
example: '1'

159
openapi/components/schemas/product_request.yaml Normal file
View File

@ -0,0 +1,159 @@
ProductRequest:
type: object
properties:
id:
type: string
description: 'The hashed product ID.'
example: eP01N
readOnly: true
assigned_user_id:
type: string
description: 'The hashed ID of the user assigned to this product.'
example: pR0j3
required: false
project_id:
type: string
description: 'The hashed ID of the project that this product is associated with.'
example: pR0j3
required: false
vendor_id:
type: string
description: 'The hashed ID of the vendor that this product is associated with.'
example: pR0j3
required: false
custom_value1:
type: string
description: 'Custom value field 1.'
example: 'Custom value 1'
required: false
custom_value2:
type: string
description: 'Custom value field 2.'
example: 'Custom value 2'
required: false
custom_value3:
type: string
description: 'Custom value field 3.'
example: 'Custom value 3'
required: false
custom_value4:
type: string
description: 'Custom value field 4.'
example: 'Custom value 4'
required: false
product_key:
type: string
description: 'The product key.'
example: '1234'
required: false
notes:
type: string
description: 'Notes about the product.'
example: 'These are some notes about the product.'
required: false
cost:
type: number
format: double
description: 'The cost of the product.'
example: 10.0
required: false
price:
type: number
format: double
description: 'The price of the product.'
example: 20.0
required: false
quantity:
type: number
format: double
description: 'The quantity of the product.'
example: 5.0
required: false
default: 1
tax_name1:
type: string
description: 'The name of tax 1.'
example: 'Tax 1'
required: false
tax_rate1:
type: number
format: double
description: 'The rate of tax 1.'
example: 10.0
required: false
tax_name2:
type: string
description: 'The name of tax 2.'
example: 'Tax 2'
required: false
tax_rate2:
type: number
format: double
description: 'The rate of tax 2.'
example: 5.0
required: false
tax_name3:
type: string
description: 'The name of tax 3.'
example: 'Tax 3'
required: false
tax_rate3:
type: number
format: double
description: 'The rate of tax 3.'
example: 0.0
required: false
in_stock_quantity:
type: integer
format: int32
description: |
The quantity of the product that is currently in stock.
**note** this field is not mutable without passing an extra query parameter which will allow modification of this value.
The query parameter ?update_in_stock_quantity=true **MUST** be passed if you wish to update this value manually.
default: 0
required: false
stock_notification:
type: boolean
description: Indicates whether stock notifications are enabled for this product
default: true
required: false
stock_notification_threshold:
type: integer
format: int32
description: The minimum quantity threshold for which stock notifications will be triggered
default: 0
required: false
max_quantity:
type: integer
format: int32
description: The maximum quantity that can be ordered for this product
required: false
product_image:
type: string
description: The URL of the product image
format: uri-reference
required: false
tax_id:
type: string
default: '1'
required: false
description: |
The tax category id for this product.'
The following constants are available (default = '1')
```
PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'
```
example: '1'

7
openapi/paths/products.yaml
View File

@ -76,6 +76,13 @@
- $ref: "#/components/parameters/X-API-TOKEN" - $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With" - $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include" - $ref: "#/components/parameters/include"
requestBody:
description: Product object that needs to be added to the company
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductRequest'
responses: responses:
200: 200:
description: "Returns the saved product object" description: "Returns the saved product object"