Merge pull request #2113 from jolelievre/admin-api-setup-dev-environement

Add page that guides the dev to setup deve environment for Admin API

Author: jolelievre

admin-api/contribute-to-core-api.md

@@ -42,6 +42,12 @@ If any issues are detected, the CI will provide helpful comments to guide you on
 - Understanding of [API Resources and our customer operations]({{< relref "/9/admin-api/resource_server/api-resources">}})
 - Understanding the conventions defined in our [CQRS API guidelines ADR](https://github.com/PrestaShop/ADR/blob/master/0023-cqrs-api-guidelines.md) (Architecture Decision Record)
 
+{{% notice note %}}
+**Setup development environment**
+
+To setup an environment where you can easily add new endpoints you can [follow this guide]({{< relref "/9/admin-api/setup-development-environment">}}).
+{{% /notice %}}
+
 ## 🎯 Objective
 
 Create REST API endpoints to manage attribute groups (AttributeGroup) with complete CRUD operations and comprehensive PHPUnit integration test coverage.

admin-api/img/api-client-list.png

@@ -0,0 +1,123 @@
+---
+title: Setup development environment
+showOnHomepage: false
+weight: 250
+---
+
+# Setup development environment
+
+This guide will show you how to setup a PrestaShop instance with the `ps_apiresources` module replaced with a Git folder and linked to your fork so you can add new endpoints.
+
+It is based on docker so a maximum of people can follow it regardless of their environment, but you can setup your environment differently and locally if you prefer.
+
+## 📋 Prerequisites
+
+- Docker
+- Git
+
+## 🎯 Objective
+
+- Install a full shop locally so you can request the Admin API
+- Replace the `ps_apiresources` module folder (installed by composer) with a Git folder, so you can create pull requests.
+- Setup an API client with basic authorization so you can use it to test the Admin API
+
+## 🏗 Setup docker environment
+
+### Setup the shop
+
+We base this guide on the `9.0.x` branch but you can use a more recent branch if you want.
+
+```bash
+git clone -b 9.0.x [email protected]:PrestaShop/PrestaShop.git prestashop-90x
+cd prestashop-90x
+make docker-start
+# The installation runs in background and takes a few minutes, you can run this command to see its progress
+make docker-logs
+# Once you see the message "Starting web server now" you're good to go
+```
+
+You should now be able to access your PrestaShop installation
+- Frontend: http://localhost:8001
+  - Login: [email protected]
+  - Password: 123456789
+- Backend: http://localhost:8001/admin-dev
+  - Login: [email protected]
+  - Password: Correct Horse Battery Staple
+- Email testing: http://localhost:1080
+
+### Setup a dev environment for the ps_apiresources module
+
+```bash
+cd modules
+rm -fR ps_apiresources
+git clone [email protected]:PrestaShop/ps_apiresources.git
+cd ps_apiresources
+# You need to fork the repository so you can add your custom fork remote, you will push your branch on it to create the PR
+git remote add fork git clone [email protected]:{myfork}/ps_apiresources.git
+git fetch fork
+
+# Go back to the root and clear the cache
+cd ../..
+make cc
+```
+
+### Create an API Client so you can use the Admin API
+
+```bash
+make docker-sh # Open a shell in the docker
+./bin/console prestashop:api-client create test --all-scopes --name='Test client' --description='Test client with all scopes' --timeout=3600 --secret=60b3045648285513cae71350b697dce3
+# You can now exit from docker shell
+```
+
+{{% notice warning %}}
+**Always use auto generated secret**
+
+The secret provided here should only be used for development, it is suggested here for convenience so developers have a common value when they discuss, but **this should never be done in production**.
+
+You should not pick your secret yourself and should let PrestaShop generate it automatically for you (the CLI option is optional, remove it and the secret is autogenerated).
+{{% /notice %}}
+
+{{% notice warning %}}
+**Never use all scopes**
+
+The security of your Admin API rely on having limited API Clients with limited access, only give your Client the bare minimum scopes they need for their usage.
+
+Each integration with an external service should rely on a dedicated API Client that has its dedicated scopes useful for this integration only.
+{{% /notice %}}
+
+Go to admin http://localhost:8001/admin-dev/configure/advanced/admin-api (login and ignore the token protection)
+
+You should see a Test client in the list, edit it to check it has all the scopes authorized
+
+![API Client list](../img/api-client-list.png)
+
+### Configure admin API for development
+
+By default, the Admin API **must** be used with HTTPs protocol, in development it's not required though but you need to disable this protection.
+
+{{% notice warning %}}
+This should only be done for development locally, never use this in production. It won't work anyway because the safety is forced all the time when you disable the debug mode of PrestaShop.
+{{% /notice %}}
+
+In the configuration uncheck the "Force security in debug mode" and save the configuration
+
+![Admin API Debug security option](../img/debug-security-option.png)
+
+### Use swagger as your client
+
+Now go to Swagger, there is a link in the Admin API index in the BO
+
+![Admin API Debug security option](../img/swagger-link.png)
+
+(or go to http://localhost:8001/admin-dev/configure/advanced/admin-api/docs.html)
+
+Click on Authorize, and use the credentials of your Api Client
+- client_id: test
+- client_secret: 60b3045648285513cae71350b697dce3
+- scopes: select all scopes if you don't want to bother and test any endpoints, however when testing your new endpoints you should select **only the scope you need** to make sure they are correctly setup
+
+![Admin API Debug security option](../img/swagger-login.png)
+
+Click on Authorize button at the bottom
+
+You can now use Swagger as your client to call the Admin API, you can also use Postman or similar tools if you prefer.