[Docs] fixes

AdamKasp · AdamKasp · commit 95b0f0a8b4fd · 2021-05-06T10:52:16.000+02:00
diff --git a/docs/api/unified_api/sylius_api_paths.rst b/docs/api/unified_api/sylius_api_paths.rst
@@ -2,8 +2,7 @@ Sylius API paths
 ================
 
 All paths in new API have the same prefix structure: ``/api/v2/admin/`` or ``/api/v2/shop/``
-Part ``/api/v2`` indicates the API version and ``/admin/`` or ``/shop/`` is necessary for authorization purpose.
-
+The ``/api/v2`` prefix part indicates the API version and the ``/admin/`` or ``/shop/`` prefixes are necessary for authorization purposes.
 When you are adding a new path to API resource configuration, you should remember to add also proper prefix.
 
 You can declare the entire path for each operation (without ``/api/v2/`` as this part is configured globally):
diff --git a/docs/customization/api.rst b/docs/customization/api.rst
@@ -1,14 +1,14 @@
 Customizing API
 ===============
 
-For create all endpoints in Sylius API we are using the API Platform.
-API Platform allows to configure endpoint by ``yaml`` and ``xml`` files or in ``annotations``.
-In these guide we will show you how to customize Sylius API endpoint with ``xml``.
+We are using the API Platform to create all endpoints in Sylius API.
+API Platform allows configuring an endpoint by ``yaml`` and ``xml`` files or by annotations.
+In this guide, you will learn how to customize Sylius API endpoints using ``xml`` configuration.
 
-How to prepare project to customization?
+How to prepare project for customization?
 ========================================
 
-For any kind of customization firstly you need to configure location of your configs.
+For any kind of customization firstly you need to configure directory with your configs.
 
 .. code-block:: yaml
     # config/packages/api_platform.yaml
@@ -22,41 +22,51 @@ For any kind of customization firstly you need to configure location of your con
     swagger:
         versions: [3]
 
-And now if you want to customize any API resource you need copy entire configuration of this resource from ``%kernel.project_dir%/vendor/sylius/sylius/src/Sylius/Bundle/ApiBundle/Resources/config/api_resources/`` to ``%kernel.project_dir%/config/api_platform``
+And now if you want to customize any API resource you need to copy the entire configuration of this resource from ``%kernel.project_dir%/vendor/sylius/sylius/src/Sylius/Bundle/ApiBundle/Resources/config/api_resources/`` to ``%kernel.project_dir%/config/api_platform``
 
-How to add an additional endpoint to a resource?
-================================================
+How to add an additional endpoint?
+==================================
 
-Let's assume that you want to add new endpoint to ``order`` which will dispatch a command.
+Let's assume that you want to add a new endpoint to the ``Order`` resource that will be dispatching a command.
 You need to add proper configuration in ``config/api_platform/Order.xml``:
 
 .. code-block:: xml
 
     <collectionOperations>
         <collectionOperation name="custom_operation">
             <attribute name="method">POST</attribute>
-            <attribute name="path">/shop/order/custom-operation</attribute>
+            <attribute name="path">/shop/orders/custom-operation</attribute>
             <attribute name="messenger">input</attribute>
             <attribute name="input">App\Command\CustomCommand</attribute>
         </collectionOperation>
     </collectionOperations>
 
-And that's all, now you have new endpoint with your custom logic.
+And that's all, now you have a new endpoint with your custom logic.
 
 .. tip::
 
     Read more about API Platform endpoint configuration `here <https://api-platform.com/docs/core/operations/>`_
 
-How to remove a resource endpoint?
-==================================
+How to remove an endpoint?
+==========================
+
+Let's assume that your shop is offering only digital products. Therefore, while checking out,
+your customers do not need to choose a shipping method for their orders.
 
-Let's assume that your shop offer only digital products so you don't need setting shipment method at all.
-To remove endpoint you only need to delete unnecessary configuration from ``config/api_platform/Order.xml``
+Thus you will need to modify the configuration file of the ``Order`` resource and remove the shipping method choosing endpoint from it.
+To remove the endpoint you only need to delete the unnecessary configuration from your ``config/api_platform/Order.xml`` which is a copied configuration file, that overwrites the one from Sylius.
+
+.. code-block:: xml
 
-How to rename the resource endpoint's path?
+    <!-- delete this configuration -->
+    <itemOperation name="shop_select_shipping_method">
+        <!-- ... -->
+    </itemOperation>
+
+How to rename an endpoint's path?
 ===========================================
 
-If you want to change endpoint's path, only what you need to do is change ``path`` attribute in your config:
+If you want to change an endpoint's path, you just need to change the ``path`` attribute in your config:
 
 .. code-block:: xml
 
@@ -67,14 +77,20 @@ If you want to change endpoint's path, only what you need to do is change ``path
             </itemOperation>
     </itemOperations>
 
-How to modify the endpoints prefixes? "shop" to "retail" rename.
-===============================================================
+How to modify the endpoints prefixes?
+=====================================
 
-Let's assume that you want to have your own prefixes on paths (for example to be more consistent with rest of your application)
-As a first step you need to change ``paths`` or ``route_prefix`` attribute in all needed resources.
-Next step is modify security configuration in ``config/packages/security.yaml``, you need to overwrite parameter:
+Let's assume that you want to have your own prefixes on paths (for example to be more consistent with the rest of your application).
+As the first step you need to change the ``paths`` or ``route_prefix`` attribute in all needed resources.
+The next step is to modify the security configuration in ``config/packages/security.yaml``, you need to overwrite the parameter:
 
 .. code-block:: xml
 
     parameters:
         sylius.security.new_api_shop_route: "%sylius.security.new_api_route%/retail"
+
+.. warning::
+
+    Changing prefixed without security configuration update can expose confidential data (like customers addresses)
+
+After these two steps you can start to use endpoints with new prefixes
