[Docs] Create an unified section about all Sylius APIs

Inventis · May 14, 2020 · d674e98 · d674e98
1 parent 92e5e60
commit d674e98
Show file tree

Hide file tree

Showing 6 changed files with 88 additions and 59 deletions.
diff --git a/docs/_themes/sylius_rtd_theme/layout.html b/docs/_themes/sylius_rtd_theme/layout.html
@@ -96,7 +96,6 @@
             <!-- Local TOC -->
             <div class="local-toc">{{ toc }}</div>
         {% endif %}
-        <a href="https://app.swaggerhub.com/apis/Sylius/sylius-shop-api/1.0.0" target="_blank" style="margin: 10px 0;">The Shop API Reference</a>
         <a href="https://sylius.com/roadmap" target="_blank"><div class="local-toc">🔔 Roadmap</div></a>
 
         <div style="padding: 30px 0;">

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -1,67 +1,20 @@
-The Sylius API
-==============
+Sylius API
+==========
 
-.. warning::
+Unified API
+-----------
 
-    The new, unified Sylius API is still under development.
+This part of the documentation is about the currently developed unified API for the Sylius platform.
 
-We have decided that we should rebuild our API and use API Platform to build a truly mature, multi-purpose API
-which can define a new standard for headless e-commerce backends.
-
-We will be supporting API Platform out-of-the-box. Secondly, it means that both APIs (Admin API and Shop API) will
-be deprecated. We are not dropping them right now, but they will not receive further development. In the later phase,
-we should provide an upgrade path for currently working apps. Last, but not least, you can already track our progress.
-All the PR’s will be aggregated `in this issue <https://github.com/Sylius/Sylius/issues/11250>`_ and the documentation
-can be already found `here <http://master.demo.sylius.com/new-api/docs>`_.
-
-Authorization
--------------
-
-In the new API all admin routes are protected by JWT authentication. If you would like to test these endpoints
-`in our Swagger UI docs <http://master.demo.sylius.com/new-api/docs>`_, you need to retrieve a JWT token first.
-You could do that by using an endpoint with default credentials for API administrators:
-
-.. image:: ../_images/sylius_api/api_platform_authentication_endpoint.png
-    :align: center
-    :scale: 50%
-
-|
-
-In the response, you will get a token that has to be passed in each request header. In the Swagger UI, you can set
-the authentication token for each request.
-
-.. image:: ../_images/sylius_api/api_platform_authentication_response.png
-    :align: center
-    :scale: 50%
-
-|
-
-Notice the **Authorize** button and unlocked padlock near the available URLs:
-
-.. image:: ../_images/sylius_api/api_platform_not_authorized.png
-    :align: center
-    :scale: 50%
-
-|
-
-Click the **Authorize** button and put the authentication token (remember about the ``Bearer`` prefix):
-
-.. image:: ../_images/sylius_api/api_platform_authorization.png
-    :align: center
-    :scale: 50%
-
-|
-
-After clicking **Authorize**, you should see locked padlock near URLs and the proper header should be added to each API call:
+.. toctree::
+    :hidden:
 
-.. image:: ../_images/sylius_api/api_platform_authorized.png
-    :align: center
-    :scale: 50%
+    unified_api/index
 
-|
+.. include:: /api/unified_api/map.rst.inc
 
-The Admin API
--------------
+Admin API
+---------
 
 This part of the documentation is about the old Admin API for the Sylius platform.
 
@@ -71,3 +24,10 @@ This part of the documentation is about the old Admin API for the Sylius platfor
     admin_api/index
 
 .. include:: /api/admin_api/map.rst.inc
+
+Shop API
+--------
+
+`Sylius Shop API <https://github.com/Sylius/ShopApiPlugin>`_ is an official plugin, providing customer-centered API.
+
+Follow the `API reference <https://app.swaggerhub.com/apis/Sylius/sylius-shop-api/1.0.0>`_ for more details.
diff --git a/docs/api/unified_api/authorization.rst b/docs/api/unified_api/authorization.rst
@@ -0,0 +1,43 @@
+Authorization
+=============
+
+In the new API all admin routes are protected by JWT authentication. If you would like to test these endpoints
+`in our Swagger UI docs <http://master.demo.sylius.com/new-api/docs>`_, you need to retrieve a JWT token first.
+You could do that by using an endpoint with default credentials for API administrators:
+
+.. image:: ../../_images/sylius_api/api_platform_authentication_endpoint.png
+    :align: center
+    :scale: 50%
+
+|
+
+In the response, you will get a token that has to be passed in each request header. In the Swagger UI, you can set
+the authentication token for each request.
+
+.. image:: ../../_images/sylius_api/api_platform_authentication_response.png
+    :align: center
+    :scale: 50%
+
+|
+
+Notice the **Authorize** button and unlocked padlock near the available URLs:
+
+.. image:: ../../_images/sylius_api/api_platform_not_authorized.png
+    :align: center
+    :scale: 50%
+
+|
+
+Click the **Authorize** button and put the authentication token (remember about the ``Bearer`` prefix):
+
+.. image:: ../../_images/sylius_api/api_platform_authorization.png
+    :align: center
+    :scale: 50%
+
+|
+
+After clicking **Authorize**, you should see locked padlock near URLs and the proper header should be added to each API call:
+
+.. image:: ../../_images/sylius_api/api_platform_authorized.png
+    :align: center
+    :scale: 50%
diff --git a/docs/api/unified_api/index.rst b/docs/api/unified_api/index.rst
@@ -0,0 +1,10 @@
+The REST API Reference
+======================
+
+.. toctree::
+    :hidden:
+
+    introduction
+    authorization
+
+.. include:: /api/unified_api/map.rst.inc
diff --git a/docs/api/unified_api/introduction.rst b/docs/api/unified_api/introduction.rst
@@ -0,0 +1,15 @@
+Introduction
+============
+
+.. warning::
+
+    The new, unified Sylius API is still under development.
+
+We have decided that we should rebuild our API and use API Platform to build a truly mature, multi-purpose API
+which can define a new standard for headless e-commerce backends.
+
+We will be supporting API Platform out-of-the-box. Secondly, it means that both APIs (Admin API and Shop API) will
+be deprecated. We are not dropping them right now, but they will not receive further development. In the later phase,
+we should provide an upgrade path for currently working apps. Last, but not least, you can already track our progress.
+All the PR’s will be aggregated `in this issue <https://github.com/Sylius/Sylius/issues/11250>`_ and the documentation
+can be already found `here <http://master.demo.sylius.com/new-api/docs>`_.
diff --git a/docs/api/unified_api/map.rst.inc b/docs/api/unified_api/map.rst.inc
@@ -0,0 +1,2 @@
+* :doc:`/api/unified_api/introduction`
+* :doc:`/api/unified_api/authorization`