Skip to content

Latest commit

 

History

History
101 lines (68 loc) · 4.08 KB

README.md

File metadata and controls

101 lines (68 loc) · 4.08 KB

Postman Collections from OpenAPI

Folder contains the code required to generate the MongoDB Atlas Postman 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 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 Collection Generation Workflow

flowchart TD
    A[Fetch the OpenAPI Specification] --> B[Apply OpenAPI Transformations]
    B --> C[Convert to Postman Collection]
    C --> D[Apply JSON transformations]
    D --> E[Upload Collection to Postman]

    style A width:260px,height:60px,text-align:center;
    style B width:260px,height:60px,text-align:center;
    style C width:260px,height:60px,text-align:center;
    style D width:260px,height:60px,text-align:center;
    style E width:260px,height:60px,text-align:center;
Loading

  1. Fetch the OpenAPI Specification: Fetch the most recent version of the OpenAPI file.

  2. Apply OpenAPI transformations: Apply transformations such as removing regex to prepare openapi file for conversion.

  3. Convert to Postman Collection: Use openapi-to-postmanv2 to convert to a Postman Collection.

  4. Apply JSON transformations: Apply transformations such as changing title, adding links, adding documentation, and preparing Collection for upload.

  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

To push to your own workspace via Postman API, create a private workspace and retrieve the workspace id

Then, create a Postman API Key that has access to this workspace

Env var setup

To test the scripts locally, you should set up the required environment variables in tools/postman/scripts by creating a local.env file populated with the following (at the minimum):

BASE_URL=""
WORKSPACE_ID=""
POSTMAN_API_KEY=""
SLACK_WEBHOOK_URL=""

Run make load-env to set your required and overriding env vars.

The OpenAPI path for Postman generation and configured feature flags can also be overriden based on provided env vars.

Running locally

Once env vars are configured, install the required dependencies:

npm install

Then, the setup scripts can be run locally using the Make following commands:

  • make fetch_openapi
  • make convert_to_collection - covert OpenAPI to Postman collection
  • make transform_collection - transform Postman collection to fix common issues
  • make transform_collection_test - test collection.
  • make upload_collection - uploads collection to the Postman

Automatic updates

Postman collection is regenerated automatically by github action release-spec.yml.