Adding documentation (#24)

* Adding documentation
* Adding instructions for maintainers

MAINTAINERS.md

@@ -0,0 +1,61 @@
+# How to run this code and contribute
+
+__NOTE : This part is meant for the authors of that repository and you probably shouldn't be doing it :)__.
+
+## Setup
+
+Most of the magic here resides in the [trigger-postman.yml](./.github/workflows/trigger-postman.yml) workflow.
+This workflow can either be triggered [directly from the UI](https://github.com/Adyen/adyen-postman/actions/workflows/trigger-postman.yml), though typically it is automatically triggered every time the [adyen-openapi](https://github.com/Adyen/adyen-openapi/blob/main/.github/workflows/notify.yml) repository is updated.
+
+
+It relies on two different custom actions : 
+
+* The [openapi-generator-postman-v2](https://github.com/gcatanese/openapi-generator-postman-v2) which is used to transform OpenAPI specifications into a Postman compatible format.
+* The [push-adyen-collections-to-postman-javascript-action](https://github.com/jlengrand/push-adyen-collections-to-postman-javascript-action/) which uses the Postman API to push those files to the [Postman AdyenDev workspace](https://www.postman.com/adyendev/workspace/adyen-apis/overview).
+
+
+## Workflow (see [trigger-postman.yml](./.github/workflows/trigger-postman.yml))
+
+When the workflow gets triggered :
+
+* The `issue` job will be fired. It is meant to warn us something needs to be checked.
+    * This job checks what new files have been created in the adyen-openapi repository
+    * Creates a [GitHub issue](https://github.com/Adyen/adyen-postman/issues) with the list of those files and assigns it to us. 
+* The `generate` job will be fired
+    * This job first runs a script relying on [openapi-generator-postman-v2](https://github.com/gcatanese/openapi-generator-postman-v2). This script will take each yaml file in the adyen-openapi repository and generate a corresponding Postman compatible version from them.
+        * The `generateAll.sh` script contains an `ALLOW_LIST` that lists all APIs that should **NOT** be ignored. Everything else (classic, webhooks, newer APIs), is ignored by default.
+        *  The `generateAll.sh` script also contains a list of `postmanVariables` and `generatedVariables` that are needed to create the variables in the Postman format.
+    * All files which have changed (been modified, or added) are then committed to the repository. 
+    * Then, the [push-adyen-collections-to-postman-javascript-action](https://github.com/jlengrand/push-adyen-collections-to-postman-javascript-action/) action will be run. This action : 
+        * Takes all Postman files in the repository
+        * Finds the highest version of each file for each API 
+        * If a new API is detected, uploads it to the AdyenDev workspace as a new collection
+        * If a newer version of an existing API is detected, patches the existing collection to the newer version
+
+## Repository secrets
+ 
+Two repository secrets are necessary to successfully run this action : 
+
+* POSTMAN_API_KEY : The API Key that will be used to interact with Postman (to push collections).
+* POSTMAN_WORKSPACE_ID : The workspace where collections will be pushed / updated.
+
+## Scripts
+
+Two custom scripts are present in the repository
+
+* `generateAll.sh` generates all postman API collection files for all versions of the OpenAPI definitions and places them in the postman folder. It is meant to run inside the [dedicated docker image](https://github.com/gcatanese/openapi-generator-postman-v2/).
+* `runDocker.sh` is the script that actually runs `generateAll.sh` inside the docker image. 
+
+## Running locally
+
+If necessary, the scripts can be run locally to achieve the same results. 
+
+* To generate Postman JSON files, one can run the `runDocker.sh` script. (Docker needs to be installed and started). 
+    * Once the generation is done, the updated files can be committed.
+* To push the collections to Postman, see the documentation of [push-adyen-collections-to-postman-javascript-action/](https://github.com/jlengrand/push-adyen-collections-to-postman-javascript-action/).
+
+Note that both scripts _should_ be safe to run without issues . The generation can be reversed via git, and you can use a dummy workspace ID for the postman script to push to a safe place for testing.
+
+## Contact
+
+For help, contact @jlengrand or @gcatanese

README.md

@@ -1,34 +1,46 @@
 # Adyen Postman
 
+**TL;DR : Visit our always up to date [Postman workspace](https://www.postman.com/adyendev/) to access all of our APIs.**
 
 This repository contains declaration files in the [Postman](https://postman.com/) format. The files are automatically generated based on the latest [adyen-openapi](https://github.com/adyen/adyen-openapi) definition files.
 They are then uploaded on our [AdyenDev](https://www.postman.com/adyendev/) Postman space and you can fork it from there. You can also directly pick the `.json` files available here and upload them if you prefer.
 
-## Usage
+## Using the [AdyenDev](https://www.postman.com/adyendev) workspace
 
-The preferred way to use these files is to fork the [Adyen APIs](https://adyendev.postman.co/workspace/Adyen-APIs~a8d63f9f-cfc7-4810-90c5-9e0c60030d3e) Postman workspace. This way you will be notified of new versions and changes.
-However, in case you want to experiment, or simply want to keep your experiments private, you can also take any of the json files in this repository and upload them yourself.
+The preferred way to use these files is to fork the [Adyen APIs](https://adyendev.postman.co/workspace/Adyen-APIs~a8d63f9f-cfc7-4810-90c5-9e0c60030d3e) Postman workspace. 
+
+![Creating a fork for a Postman collection](./images/create-fork.gif)
+
+
+This way you will be notified of new versions and changes per email and in the UI directly.
+
+![Receiving the email of a collection changed](./images/postman-email.png)
+
+## Importing the JSON files
+
+However, in case you want to experiment, want to keep your experiments, want to use an older version of any of our APIs or if you're using a postman alternative like [Insomnia](https://docs.insomnia.rest/insomnia/import-export-data), you can also take any of the json files in this repository and upload them yourself.
 
 ![Importing a json file as a Postman collection](./images/import-postman.gif)
 
-
-## Contributing
-
-We encourage you to contribute to our repository. Find out more in our [contribution guidelines](https://github.com/Adyen/.github/blob/master/CONTRIBUTING.md).
-However, for anything related to our APIs, the correct repository to contribute to would be [adyen-openapi](https://github.com/adyen/adyen-openapi).
-
 ## Setup
 
-* `generateAll.sh` generates all postman API collection files for all versions of the OpenAPI definitions and places them in the postman folder. It is meant to run inside the [dedicated docker image](https://github.com/gcatanese/openapi-generator-postman-v2/).
-* `runDocker.sh` is the script that actually runs `generateAll.sh` inside the docker image. 
+Before running API calls, you will have to set some variables. Those depend on which API you are using, but you will recognize them because they are between braces (`{{X-API-Key}}`).
+Notably, you will find those in the `Authorization` as well as the `Variables` tabs in each collection. 
 
-This step should only be done for initial setup, or if something goes wrong. Most work should be automated in the GitHub workflows.
+![Variables to set in my collection](./images/collection-variables.png).
+
+Instead of directly modifying them there, we recommend you instead to create [Environments](https://learning.postman.com/docs/sending-requests/managing-environments/). This way, you can switch from test to production without much hassle when running your API calls. Environments are also nice to protect secret values, like your API Keys. 
+
+To do this, you can either :
+
+* Fork the [Adyen APIs](https://www.postman.com/adyendev/workspace/adyen-apis/overview) environment we provide, and override the variables there.
+* Create a new environment from scratch using the corresponding left tab in the Postman UI, and override the variables there.
+
+![An example of environment](./images/environment.png).
 
-## Documentation
-Link to relevant documentation and next steps that have to be taken.
 
 ## Support
-If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue. For other questions, contact our [support team](https://www.adyen.help/hc/en-us/requests/new).
+If you have a feature request, or spotted a bug or a technical problem, [create a GitHub issue](https://github.com/Adyen/adyen-postman/issues/new/choose). For other questions, contact our [support team](https://www.adyen.help/hc/en-us/requests/new).
 
 ## License
 MIT license. For more information, see the LICENSE file.

runDocker.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+  #!/bin/sh
 
 if [ ! -d /adyen-openapi ]; then
   git clone https://github.com/Adyen/adyen-openapi.git