From 65057e9be9f075e9031f18d009d1a582a235b669 Mon Sep 17 00:00:00 2001 From: Wojciech Trocki Date: Mon, 9 Dec 2024 11:12:01 +0100 Subject: [PATCH] CLOUDP-278958: improve postman documentation --- .github/workflows/release-postman.yml | 2 +- tools/postman/README.md | 37 ++++++++++++++++----------- 2 files changed, 23 insertions(+), 16 deletions(-) diff --git a/.github/workflows/release-postman.yml b/.github/workflows/release-postman.yml index e66dd4d61b..89ae19b295 100644 --- a/.github/workflows/release-postman.yml +++ b/.github/workflows/release-postman.yml @@ -3,7 +3,7 @@ on: workflow_call: inputs: atlas_prod_base_url: - description: 'Base URL of Atlas.' + description: Base URL of Atlas required: true type: string secrets: # all secrets are passed explicitly in this workflow diff --git a/tools/postman/README.md b/tools/postman/README.md index 2e78671ab7..b20f937390 100644 --- a/tools/postman/README.md +++ b/tools/postman/README.md @@ -1,25 +1,21 @@ # Postman Collections from OpenAPI -This folder contains the code required to generate the MongoDB Atlas Postman collections from the MongoDB OpenAPI Specification. All scripts can be run locally if the environment variables for POSTMAN_API_KEY, WORKSPACE_ID, BASE_URL, and SLACK_WEBHOOK_URL are set +Folder contains the code required to generate the [MongoDB Atlas Postman collections](https://www.postman.com/mongodb-devrel?tab=collections). +Collections are generated from from the MongoDB OpenAPI Specification. ## Purpose of the project Scripts allow for the generation of Postman collections from OpenAPI specifications. This allows -the [DevRel Postman workspace](https://www.postman.com/mongodb-devrel) to stay up to date with the latest version of the +the [DevRel Postman workspace](https://www.postman.com/mongodb-devrel?tab=collections) to stay up to date with the latest version of the API. +Process of updating involves: + 1. Fetching OpenAPI file 2. Converting OpenAPI file to Postman Collection 3. Updating information about the Collection 4. Uploading the Collection to Postman -## Postman folder structure - -- `openapi` - Where the OpenAPI Spec, version information, and fork files are stored -- `tmp` - Where the Postman Collection is generated and the temporary working files are stored -- `scripts` - Where the Bash scripts are stored -- `validation` - Where the files for spectral validation of the generated collection is stored - ## Postman Collection Generation Workflow ```mermaid @@ -48,6 +44,20 @@ flowchart TD 5. **Upload Collection to Postman**: Use the Postman API to upload the Collection to Postman. +## Limitations + +Our Postman collection generation has several limitations, meaning some manual user actions may be necessary during setup: + +- Only a single content-type header is supported generation, meaning users may have to manually update this header if the API supports more than one; see docs links on endpoint level +- Only a single auth scheme is supported during generation, meaning users may have to update their auth on the collection level or endpoint level if not selecting the default + +## Postman folder structure + +- `openapi` - Where the OpenAPI Spec, version information, and fork files are stored +- `tmp` - Where the Postman Collection is generated and the temporary working files are stored +- `scripts` - Where the Bash scripts are stored +- `validation` - Where the files for spectral validation of the generated collection is stored + ## Local setup and validation ### Prerequisites @@ -64,6 +74,7 @@ To test the scripts locally, you should set up the required environment variable BASE_URL="" WORKSPACE_ID="" POSTMAN_API_KEY="" +SLACK_WEBHOOK_URL="" ``` Run `make load-env` to set your required and overriding env vars. @@ -78,10 +89,6 @@ Once env vars are configured, the setup scripts can be run locally using the Mak - `make transform_collection` - `make upload_collection` +## Automatic updates -### Limitations - -Our Postman collection generation has several limitations, meaning some manual user actions may be necessary during setup: - -- Only a single content-type header is supported generation, meaning users may have to manually update this header if the API supports more than one; see docs links on endpoint level -- Only a single auth scheme is supported during generation, meaning users may have to update their auth on the collection level or endpoint level if not selecting the default \ No newline at end of file +Postman collection is regerented automatically by github action [`release-spec.yml`](../../.github/workflows/release-spec.yml)