From cca432040af9adbc0544aab165db458f47bc4c41 Mon Sep 17 00:00:00 2001 From: SamuelMartini Date: Fri, 24 Jan 2020 15:31:02 +0100 Subject: [PATCH 1/6] Hightlight how the AddressBook endpoint manage addresses This commit provides some context on how the address book logic works when managing user addresses. --- api/openapi/api.oas2.yml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/api/openapi/api.oas2.yml b/api/openapi/api.oas2.yml index 818630195fd..f7e48397c09 100644 --- a/api/openapi/api.oas2.yml +++ b/api/openapi/api.oas2.yml @@ -999,7 +999,10 @@ paths: '422': $ref: '#/responses/delete-restriction' summary: Remove address from user address book - description: Removes an address from a user's address book. + description: |- + Removes an address from a user's address book. + + **Note:** Rather than delete a `Spree::UserAddress` record this action set its `archived` attribute to `true`. operationId: remove-address-from-user-address-book tags: - Address books @@ -1030,7 +1033,11 @@ paths: name: body schema: $ref: '#/definitions/address-book-input' - description: Updates a user's address book. + description: |- + Updates a user's address book. + + **Note:** if the passed `id` matches an existing `address` a new `Spree::Address` record will be created and the matched `address` `archived` on `Spree::UserAddress`. For a similar logic, if the passed `id` matches an existing `address` which is in `archived` state, the `Spree::UserAddress#archived` record will be restored to `false`. + See `user_address_book.rb` for further information. security: - api-key: [] '/users/{user_id}/credit_cards': From 3c9c8857e653b1aecff26ec2419d326dcae3aadf Mon Sep 17 00:00:00 2001 From: SamuelMartini Date: Fri, 24 Jan 2020 15:58:27 +0100 Subject: [PATCH 2/6] Add checkout_id description to openapi doc Being Spree::CheckoutController a custom controller with not resource, it may not be clear what `checkout_id` is. --- api/openapi/api.oas2.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/api/openapi/api.oas2.yml b/api/openapi/api.oas2.yml index f7e48397c09..5cb51d4d3da 100644 --- a/api/openapi/api.oas2.yml +++ b/api/openapi/api.oas2.yml @@ -1097,6 +1097,7 @@ paths: in: path type: string required: true + description: The order number - name: id in: path type: string @@ -1159,6 +1160,7 @@ paths: in: path type: string required: true + description: The order number post: responses: '200': @@ -1208,6 +1210,7 @@ paths: in: path type: string required: true + description: The order number - name: id in: path type: string @@ -1277,6 +1280,7 @@ paths: in: path type: string required: true + description: The order number post: responses: '200': @@ -1323,6 +1327,7 @@ paths: in: path type: string required: true + description: The order number - name: id in: path type: string @@ -3357,6 +3362,7 @@ paths: in: path type: string required: true + description: The order number - name: id in: path type: string @@ -3643,6 +3649,7 @@ paths: in: path type: string required: true + description: The order number - name: payment_id in: path type: string @@ -3672,6 +3679,7 @@ paths: in: path type: string required: true + description: The order number - name: payment_id in: path type: string @@ -3701,6 +3709,7 @@ paths: in: path type: string required: true + description: The order number - name: payment_id in: path type: string @@ -3730,6 +3739,7 @@ paths: in: path type: string required: true + description: The order number - name: payment_id in: path type: string @@ -3759,6 +3769,7 @@ paths: in: path type: string required: true + description: The order number - name: payment_id in: path type: string @@ -3788,6 +3799,7 @@ paths: in: path type: string required: true + description: The order number - name: return_authorization_id in: path type: string @@ -3818,6 +3830,7 @@ paths: in: path type: string required: true + description: The order number '/checkouts/{checkout_id}/complete': put: responses: @@ -3852,6 +3865,7 @@ paths: in: path type: string required: true + description: The order number '/checkouts/{checkout_id}/next': put: responses: @@ -3886,6 +3900,7 @@ paths: in: path type: string required: true + description: The order number /classifications: put: responses: @@ -4369,6 +4384,7 @@ paths: in: path type: string required: true + description: The order number '/orders/{order_number}/coupon_codes': post: responses: From 4e2a55598d7a706c4381b28d926a8a5b261ab4cd Mon Sep 17 00:00:00 2001 From: SamuelMartini Date: Fri, 24 Jan 2020 17:06:13 +0100 Subject: [PATCH 3/6] Inform on side effects of Spree::Api::CheckoutsController#update One could not expect to advance the order state machine or to have a 422 response. --- api/openapi/api.oas2.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api/openapi/api.oas2.yml b/api/openapi/api.oas2.yml index 5cb51d4d3da..a72d39582d4 100644 --- a/api/openapi/api.oas2.yml +++ b/api/openapi/api.oas2.yml @@ -3547,7 +3547,10 @@ paths: '422': $ref: '#/responses/unprocessable-entity' summary: Update checkout - description: Updates a checkout. + description: |- + Updates a checkout. + + **Note:** In addition to the order update, this action always attempts to perform an order state machine transition which results in a `422` response if it cannot be transitioned. operationId: update-checkout tags: - Checkouts From 9ace5bb094349ab652eb515a432b05ad434f37ca Mon Sep 17 00:00:00 2001 From: SamuelMartini Date: Fri, 24 Jan 2020 17:20:10 +0100 Subject: [PATCH 4/6] Inform on the deprecation of OrdersController#apply_coupon_code Documentation should warn on the deprecation of the method and provide an alternative. --- api/openapi/api.oas2.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api/openapi/api.oas2.yml b/api/openapi/api.oas2.yml index a72d39582d4..c5bb46110dc 100644 --- a/api/openapi/api.oas2.yml +++ b/api/openapi/api.oas2.yml @@ -3949,7 +3949,10 @@ paths: '422': $ref: '#/responses/unprocessable-entity' summary: Apply order coupon code - description: Applies a coupon code on the order. + description: |- + **Deprecated:** This method is deprecated. Please use `Spree::Api::CouponCodesController#create` endpoint instead. + + Applies a coupon code on the order. operationId: apply-order-coupon-code tags: - Coupon codes From adbcbf52b5c155b8336313b6d0ca7dbe0b243195 Mon Sep 17 00:00:00 2001 From: SamuelMartini Date: Fri, 24 Jan 2020 18:23:36 +0100 Subject: [PATCH 5/6] Add description to coupon controller post paramenter Explain that `id` paramenter is the coupon code --- api/openapi/api.oas2.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/openapi/api.oas2.yml b/api/openapi/api.oas2.yml index c5bb46110dc..d76e4da9c5b 100644 --- a/api/openapi/api.oas2.yml +++ b/api/openapi/api.oas2.yml @@ -3429,6 +3429,7 @@ paths: in: path type: string required: true + description: This is the coupon code '/orders/{order_number}/line_items/{id}': delete: responses: From c41339ae5f0d2c19833b6cca8ba7911214abbf65 Mon Sep 17 00:00:00 2001 From: SamuelMartini Date: Fri, 24 Jan 2020 18:34:20 +0100 Subject: [PATCH 6/6] Add description for Spree::Api::Classifications#update method Better describe how the action only affect the classification position --- api/openapi/api.oas2.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api/openapi/api.oas2.yml b/api/openapi/api.oas2.yml index d76e4da9c5b..98aa217df75 100644 --- a/api/openapi/api.oas2.yml +++ b/api/openapi/api.oas2.yml @@ -3918,7 +3918,10 @@ paths: '422': $ref: '#/responses/unprocessable-entity' summary: Update classification - description: Updates a classification. + description: |- + Updates a classification. + + This method only updates the classification position. operationId: update-classification tags: - Classifications