From 49651dd37eba3345679a532fb0e466e0acb6108e Mon Sep 17 00:00:00 2001 From: Beppe Catanese Date: Fri, 8 Sep 2023 14:16:11 +0200 Subject: [PATCH] Update doc --- MAINTAINERS.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 5efe846..a91af9c 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -7,15 +7,17 @@ __NOTE : This part is meant for the authors of that repository and you probably 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. -Two othew workflows are provided for 'ad-hoc' operations: -* [create-collection.yml](./.github/workflows/create-collection.yml) is provided to create a new collection from a given OpenAPI file -* [update-collection.yml](./.github/workflows/update-collection.yml) is provided to update an existing collection from a given OpenAPI file +Othew workflows are provided for 'ad-hoc' operations: +* [generate.yml](./.github/workflows/generate.yml) is provided to generate a Postman JSON file from an OpenAPI file +* [create-collection.yml](./.github/workflows/create-collection.yml) is provided to create (POST) a new collection in Postman.com +* [update-collection.yml](./.github/workflows/update-collection.yml) is provided to update (PUT) an existing collection in Postman.com The workflows rely on 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). +* The [push-to-postman-action](https://github.com/gcatanese/push-to-postman-action) that pushes a single file to Postman.com. ## Workflow trigger-postman (see [trigger-postman.yml](./.github/workflows/trigger-postman.yml)) @@ -36,29 +38,33 @@ When the workflow gets triggered : * 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 +## Workflow generate (see [generate.yml](./.github/workflows/generate.yml)) + +It requires 1 input variable: **file** (OpenAPI file path within the `adyen-openapi` repository). + +The workflow can be executed manually (on-demand) and will perform the following: +* generate the Postman collection (as JSON file) +* commit Postman JSON into the repository + +The `generatePostmanJsonFile.sh` script contains a list of `postmanVariables` and `generatedVariables` that are needed to create the variables in the Postman format. + +This job first runs a script relying on [openapi-generator-postman-v2](https://github.com/gcatanese/openapi-generator-postman-v2). + ## Workflow create-collection (see [create-collection.yml](./.github/workflows/create-collection.yml)) It requires 2 input variables: **file** (OpenAPI file path within the `adyen-openapi` repository) and **workspaceId** (Postman workspace ID where the collection will be created). The workflow can be executed manually (on-demand) and will perform the following: +* push (POST) the Postman JSON file to Postman.com -* 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 the file passed as parameter (ie `adyen-openapi/yaml/CheckoutService-v70.yaml) and generate a corresponding Postman compatible version. - * The `createCollection.sh` script contains a list of `postmanVariables` and `generatedVariables` that are needed to create the variables in the Postman format. - * The Postman collection is pushed (POST) to Postman. - * The generated JSON file when it has changed (been modified, or added) is committed to the repository. ## Workflow update-collection (see [update-collection.yml](./.github/workflows/update-collection.yml)) It requires 2 input variables: **file** (OpenAPI file path within the `adyen-openapi` repository) and **collectionId** (ID of the Postman collection to be updated). The workflow can be executed manually (on-demand) and will perform the following: +* push (PUT) the Postman JSON file to Postman.com -* 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 the file passed as parameter (ie `adyen-openapi/yaml/CheckoutService-v70.yaml) and generate a corresponding Postman compatible version. - * The `updateCollection.sh` script contains a list of `postmanVariables` and `generatedVariables` that are needed to create the variables in the Postman format. - * The Postman collection is pushed (PUT) to Postman. - * The generated JSON file when it has changed (been modified, or added) is committed to the repository. ## Repository secrets @@ -73,8 +79,7 @@ The repository includes multiple scripts: * `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. -* `createCollection.sh` (*) generates the postman API collection for a given OpenAPI file and creates a new collection in Postman. -* `updateCollection.sh` (*) generates the postman API collection for a given OpenAPI file and updates an existing collection in Postman. +* `generatePostmanJsonFile.sh` (*) generates the postman JSON file for a given OpenAPI file. (*) all scripts should be made executable (`chmod +x filename.sh`) as they are run by the GitHub action