asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: fixes to the API reference (#2570)

Browse Source
This commit is contained in:
Shahed Nasser
2022-11-09 18:24:48 +02:00
committed by GitHub
parent 9e7e8c6d51
commit 884322447e
23 changed files with 306 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/medusa/src/api/routes/admin/currencies/list-currencies.ts
+28 -12
View File
@@ -15,9 +15,25 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
* parameters:
* - (query) code {string} Code of the currency to search for.
* - (query) includes_tax {boolean} Search for tax inclusive currencies.
* - (query) order {string} to retrieve products in.
* - (query) offset {string} How many products to skip in the result.
* - (query) limit {string} Limit the number of products returned.
* - (query) order {string} order to retrieve products in.
* - (query) offset=0 {number} How many products to skip in the result.
* - (query) limit=20 {number} Limit the number of products returned.
* x-codeSamples:
* - lang: JavaScript
* label: JS Client
* source: |
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.currencies.list()
* .then(({ currencies, count, offset, limit }) => {
* console.log(currencies.length);
* });
* - lang: Shell
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/currencies' \
* --header 'Authorization: Bearer {api_token}'
* tags:
* - Currency
* responses:
@@ -27,19 +43,19 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
* application/json:
* schema:
* properties:
* count:
* description: The number of Currency.
* type: integer
* offset:
* description: The offset of the Currency query.
* type: integer
* limit:
* description: The limit of the currency query.
* type: integer
* currencies:
* type: array
* items:
* $ref: "#/components/schemas/currency"
* count:
* type: integer
* description: The total number of items available
* offset:
* type: integer
* description: The number of items skipped before these items
* limit:
* type: integer
* description: The number of items per page
*/
export default async (req: ExtendedRequest<Currency>, res) => {
const currencyService: CurrencyService = req.scope.resolve("currencyService")
packages/medusa/src/api/routes/admin/currencies/update-currency.ts
+22
View File
@@ -21,6 +21,28 @@ import TaxInclusivePricingFeatureFlag from "../../../../loaders/feature-flags/ta
* includes_tax:
* type: boolean
* description: "[EXPERIMENTAL] Tax included in prices of currency."
* x-codeSamples:
* - lang: JavaScript
* label: JS Client
* source: |
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.currencies.update(code, {
* includes_tax: true
* })
* .then(({ currency }) => {
* console.log(currency.id);
* });
* - lang: Shell
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/currencies/{code}' \
* --header 'Authorization: Bearer {api_token}' \
* --header 'Content-Type: application/json' \
* --data-raw '{
* "includes_tax": true
* }'
* tags:
* - Currency
* responses:
packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
+27 -6
View File
@@ -15,6 +15,23 @@ import {
* description: "Create an OrderEdit LineItem."
* parameters:
* - (path) id=* {string} The ID of the Order Edit.
* requestBody:
* content:
* application/json:
* schema:
* required:
* - variant_id
* - quantity
* properties:
* variant_id:
* description: The ID of the variant ID to add
* type: string
* quantity:
* description: The quantity to add
* type: number
* metadata:
* description: An optional set of key-value pairs to hold additional information.
* type: object
* x-authenticated: true
* x-codeSamples:
* - lang: JavaScript
@@ -23,16 +40,20 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdit.addLineItem(order_edit_id, { variant_id, quantity })
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
* medusa.admin.orderEdits.addLineItem(order_edit_id, {
* variant_id,
* quantity
* })
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
* - lang: Shell
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items' \
* --header 'Authorization: Bearer {api_token}'
* -d '{ "variant_id": "some_variant_id", "quantity": 3 }'
* --header 'Authorization: Bearer {api_token}' \
* --header 'Content-Type: application/json' \
* --data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", "quantity": 3 }'
* security:
* - api_token: []
* - cookie_auth: []
packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts
+2 -2
View File
@@ -21,14 +21,14 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdit.cancel(orderEditId)
* medusa.admin.orderEdits.cancel(order_edit_id)
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
* - lang: Shell
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/:id/cancel' \
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \
* --header 'Authorization: Bearer {api_token}'
* security:
* - api_token: []
packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts
+2 -2
View File
@@ -21,14 +21,14 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdit.confirm(orderEditId)
* medusa.admin.orderEdits.confirm(order_edit_id)
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
* - lang: Shell
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/:id/confirm' \
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \
* --header 'Authorization: Bearer {api_token}'
* security:
* - api_token: []
packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts
+17 -3
View File
@@ -12,6 +12,19 @@ import {
* operationId: "PostOrderEdits"
* summary: "Create an OrderEdit"
* description: "Creates an OrderEdit."
* requestBody:
* content:
* application/json:
* schema:
* required:
* - order_id
* properties:
* order_id:
* description: The ID of the order to create the edit for.
* type: string
* internal_note:
* description: An optional note to create for the order edit.
* type: string
* x-authenticated: true
* x-codeSamples:
* - lang: JavaScript
@@ -20,7 +33,7 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdit.create({ order_id, internal_note })
* medusa.admin.orderEdits.create({ order_id })
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
@@ -28,8 +41,9 @@ import {
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/order-edits' \
* --header 'Authorization: Bearer {api_token}'
* -d '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }'
* --header 'Authorization: Bearer {api_token}' \
* --header 'Content-Type: application/json' \
* --data-raw '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }'
* security:
* - api_token: []
* - cookie_auth: []
packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
+1 -1
View File
@@ -17,7 +17,7 @@ import { OrderEditService } from "../../../../services"
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdits.deleteItemChange(item_change_id, order_edit_id)
* medusa.admin.orderEdits.deleteItemChange(order_edit_id, item_change_id)
* .then(({ id, object, deleted }) => {
* console.log(id)
* })
packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
+1 -1
View File
@@ -16,7 +16,7 @@ import { OrderEditService } from "../../../../services"
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdits.delete(edit_id)
* medusa.admin.orderEdits.delete(order_edit_id)
* .then(({ id, object, deleted }) => {
* console.log(id)
* })
packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
+1 -1
View File
@@ -19,7 +19,7 @@ import { FindParams } from "../../../../types/common"
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdit.retrieve(orderEditId)
* medusa.admin.orderEdits.retrieve(orderEditId)
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts
+12 -3
View File
@@ -23,9 +23,9 @@ import { IsOptional, IsString } from "class-validator"
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdit.list()
* .then(({ order_edits }) => {
* console.log(order_edits)
* medusa.admin.orderEdits.list()
* .then(({ order_edits, count, limit, offset }) => {
* console.log(order_edits.length)
* })
* - lang: Shell
* label: cURL
@@ -47,6 +47,15 @@ import { IsOptional, IsString } from "class-validator"
* order_edits:
* type: array
* $ref: "#/components/schemas/order_edit"
* count:
* type: integer
* description: The total number of items available
* offset:
* type: integer
* description: The number of items skipped before these items
* limit:
* type: integer
* description: The number of items per page
* "400":
* $ref: "#/components/responses/400_error"
* "401":
packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
+1 -1
View File
@@ -20,7 +20,7 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdits.requestConfirmation(edit_id)
* medusa.admin.orderEdits.requestConfirmation(order_edit_id)
* .then({ order_edit }) => {
* console.log(order_edit.id)
* })
packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
+16 -3
View File
@@ -16,6 +16,16 @@ import {
* parameters:
* - (path) id=* {string} The ID of the Order Edit to update.
* - (path) item_id=* {string} The ID of the order edit item to update.
* requestBody:
* content:
* application/json:
* schema:
* required:
* - quantity
* properties:
* quantity:
* description: The quantity to update
* type: number
* x-codeSamples:
* - lang: JavaScript
* label: JS Client
@@ -23,7 +33,9 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orderEdits.updateLineItem(order_edit_id, line_item_id)
* medusa.admin.orderEdits.updateLineItem(order_edit_id, line_item_id, {
* quantity: 5
* })
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
@@ -31,8 +43,9 @@ import {
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \
* --header 'Authorization: Bearer {api_token}'
* -d '{ "quantity": 5 }'
* --header 'Authorization: Bearer {api_token}' \
* --header 'Content-Type: application/json' \
* --data-raw '{ "quantity": 5 }'
* security:
* - api_token: []
* - cookie_auth: []
packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
+12 -3
View File
@@ -16,6 +16,14 @@ import {
* x-authenticated: true
* parameters:
* - (path) id=* {string} The ID of the OrderEdit.
* requestBody:
* content:
* application/json:
* schema:
* properties:
* internal_note:
* description: An optional note to create or update for the order edit.
* type: string
* x-codeSamples:
* - lang: JavaScript
* label: JS Client
@@ -23,8 +31,9 @@ import {
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* const params = {internal_note: "internal reason XY"}
* medusa.admin.orderEdit.update(orderEditId, params)
* medusa.admin.orderEdits.update(order_edit_id, {
* internal_note: "internal reason XY"
* })
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
@@ -32,7 +41,7 @@ import {
* label: cURL
* source: |
* curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}' \
* --header 'Authorization: Bearer {api_token}'
* --header 'Authorization: Bearer {api_token}' \
* --header 'Content-Type: application/json' \
* --data-raw '{
* "internal_note": "internal reason XY"
packages/medusa/src/api/routes/admin/returns/receive-return.ts
+2 -2
View File
@@ -58,8 +58,8 @@ import { isDefined } from "../../../../utils"
* }
* ]
* })
* .then(({ return }) => {
* console.log(return.id);
* .then((data) => {
* console.log(data.return.id);
* });
* - lang: Shell
* label: cURL
packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts
+1 -1
View File
@@ -21,7 +21,7 @@ import { MedusaError } from "medusa-core-utils"
* source: |
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* medusa.orderEdit.complete(orderEditId)
* medusa.orderEdits.complete(order_edit_id)
* .then(({ order_edit }) => {
* console.log(order_edit.id)
* })
packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts
+1 -1
View File
@@ -28,7 +28,7 @@ import {
* source: |
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* medusa.orderEdit.decline(orderEditId)
* medusa.orderEdits.decline(order_edit_id)
* .then(({ order_edit }) => {
* console.log(order_edit.id);
* })
packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts
+1 -1
View File
@@ -14,7 +14,7 @@ import { OrderEditService } from "../../../../services"
* source: |
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* medusa.orderEdit.retrieve(orderEditId)
* medusa.orderEdits.retrieve(order_edit_id)
* .then(({ order_edit }) => {
* console.log(order_edit.id);
* });
packages/medusa/src/api/routes/store/products/list-products.ts
+9
View File
@@ -45,6 +45,15 @@ import { IsType } from "../../../../utils/validators/is-type"
* items:
* type: string
* - in: query
* name: sales_channel_id
* style: form
* explode: false
* description: an array of sales channel IDs to filter the retrieved products by.
* schema:
* type: array
* items:
* type: string
* - in: query
* name: collection_id
* style: form
* explode: false
packages/medusa/src/api/routes/store/returns/create-return.ts
+2 -2
View File
@@ -76,8 +76,8 @@ import { validator } from "../../../../utils/validator"
* }
* ]
* })
* .then(({ return }) => {
* console.log(return.id);
* .then((data) => {
* console.log(data.return.id);
* });
* - lang: Shell
* label: cURL
packages/medusa/src/models/order-edit.ts
+27 -3
View File
@@ -141,11 +141,11 @@ export class OrderEdit extends BaseEntity {
* description: The ID of the order that is edited
* example: order_01G2SG30J8C85S4A5CHM2S1NS2
* order:
* description: Order object
* description: Available if the relation `order` is expanded.
* $ref: "#/components/schemas/order"
* changes:
* type: array
* description: Line item changes array.
* description: Available if the relation `changes` is expanded.
* items:
* $ref: "#/components/schemas/order_item_change"
* internal_note:
@@ -211,9 +211,33 @@ export class OrderEdit extends BaseEntity {
* type: integer
* description: The difference between the total amount of the order and total amount of edited order.
* example: 8200
* status:
* type: string
* description: The status of the order edit.
* enum:
* - confirmed
* - declined
* - requested
* - created
* - canceled
* items:
* type: array
* description: Computed line items from the changes.
* description: Available if the relation `items` is expanded.
* items:
* $ref: "#/components/schemas/line_item"
* payment_collection_id:
* type: string
* description: The ID of the payment collection
* example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
* payment_collection:
* description: Available if the relation `payment_collection` is expanded.
* $ref: "#/components/schemas/payment_collection"
* created_at:
* type: string
* description: "The date with timezone at which the resource was created."
* format: date-time
* updated_at:
* type: string
* description: "The date with timezone at which the resource was updated."
* format: date-time
*/
packages/medusa/src/models/order-item-change.ts
+20 -4
View File
@@ -73,7 +73,7 @@ export class OrderItemChange extends SoftDeletableEntity {
* example: oic_01G8TJSYT9M6AVS5N4EMNFS1EK
* type:
* type: string
* description: The order's status
* description: The order item change's status
* enum:
* - item_add
* - item_remove
@@ -83,20 +83,36 @@ export class OrderItemChange extends SoftDeletableEntity {
* description: The ID of the order edit
* example: oe_01G2SG30J8C85S4A5CHM2S1NS2
* order_edit:
* description: Order edit object
* description: Available if the relation `order_edit` is expanded.
* $ref: "#/components/schemas/order_edit"
* original_line_item_id:
* type: string
* description: The ID of the original line item in the order
* example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
* original_line_item:
* description: Original line item object.
* description: Available if the relation `original_line_item` is expanded.
* $ref: "#/components/schemas/line_item"
* line_item_id:
* type: string
* description: The ID of the cloned line item.
* example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
* line_item:
* description: Line item object.
* description: Available if the relation `line_item` is expanded.
* $ref: "#/components/schemas/line_item"
* created_at:
* type: string
* description: "The date with timezone at which the resource was created."
* format: date-time
* updated_at:
* type: string
* description: "The date with timezone at which the resource was updated."
* format: date-time
* deleted_at:
* type: string
* description: "The date with timezone at which the resource was deleted."
* format: date-time
* metadata:
* type: object
* description: An optional key-value map with additional details
* example: {car: "white"}
*/
packages/medusa/src/models/payment-collection.ts
+100
View File
@@ -111,3 +111,103 @@ export class PaymentCollection extends SoftDeletableEntity {
this.id = generateEntityId(this.id, "paycol")
}
}
/**
* @schema payment_collection
* title: "Payment Collection"
* description: "Payment Collection"
* x-resourceId: payment_collection
* required:
* - type
* - status
* - amount
* - region_id
* - currency_code
* - created_by
* properties:
* id:
* type: string
* description: The payment collection's ID
* example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
* type:
* type: string
* description: The type of the payment collection
* enum:
* - order_edit
* status:
* type: string
* description: The type of the payment collection
* enum:
* - not_paid
* - awaiting
* - authorized
* - partially_authorized
* - captured
* - partially_captured
* - refunded
* - partially_refunded
* - canceled
* - requires_action
* description:
* type: string
* description: Description of the payment collection
* amount:
* type: number
* description: Amount of the payment collection.
* authorized_amount:
* type: number
* description: Authorized amount of the payment collection.
* captured_amount:
* type: number
* description: Captured amount of the payment collection.
* refunded_amount:
* type: number
* description: Refunded amount of the payment collection.
* region_id:
* type: string
* description: The region's ID
* example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
* region:
* description: Available if the relation `region` is expanded.
* $ref: "#/components/schemas/region"
* currency_code:
* description: "The 3 character ISO code for the currency."
* type: string
* example: usd
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
* description: See a list of codes.
* currency:
* description: Available if the relation `currency` is expanded.
* $ref: "#/components/schemas/currency"
* payment_sessions:
* type: array
* description: Available if the relation `payment_sessions` is expanded.
* items:
* $ref: "#/components/schemas/payment_session"
* payments:
* type: array
* description: Available if the relation `payments` is expanded.
* items:
* $ref: "#/components/schemas/payment"
* created_by:
* type: string
* description: "The ID of the user that created the payment collection."
* created_at:
* type: string
* description: "The date with timezone at which the resource was created."
* format: date-time
* updated_at:
* type: string
* description: "The date with timezone at which the resource was updated."
* format: date-time
* deleted_at:
* type: string
* description: "The date with timezone at which the resource was deleted."
* format: date-time
* metadata:
* type: object
* description: An optional key-value map with additional details
* example: {car: "white"}
*/
packages/medusa/src/models/region.ts
+1 -1
View File
@@ -118,7 +118,7 @@ export class Region extends SoftDeletableEntity {
* properties:
* id:
* type: string
* description: The cart's ID
* description: The region's ID
* example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
* name:
* description: "The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name."