Yes, let's build it.
This is a fantastic workflow for creating an accurate, up-to-date spec based on what your API is *actually* returning.
We can build this automation pipeline easily by combining three open-source tools: `newman`, `newman-reporter-har`, and `har-to-openapi`. The entire process can be built into a single, repeatable script.
Here is the step-by-step guide to building your automated spec generator.
-----
### 🛠️ The Toolkit We'll Use
1. **`newman`**: The command-line runner for Postman. It runs your collection.
2. **`newman-reporter-har`**: A plugin for `newman`. It listens to the run and records all traffic (requests and responses) into a `.har` (HTTP Archive) file.
3. **`har-to-openapi`**: A utility that converts the `.har` file into a beautiful `openapi.yaml` spec.
### ⚙️ Step 1: Set Up the Project
First, let's set this up in a project folder.
1. Create a new folder for your project (e.g., `api-spec-generator`).
2. In that folder, export your Postman Collection as `collection.json` and your Environment as `environment.json`.
3. Initialize an `npm` project (this lets us save the tools and scripts):
```bash
npm init -y
```
4. Install the three tools as development dependencies:
```bash
npm install --save-dev newman newman-reporter-har har-to-openapi
```
### 🚀 Step 2: Build the Automation Script
Now, we'll add a script to your **`package.json`** file. This file acts as our "build" system.
Open your `package.json` file and add the following `scripts` section.
```json
{
"name": "api-spec-generator",
"version": "1.0.0",
"scripts": {
"generate:spec": "npm run newman && npm run convert",
"newman": "newman run collection.json -e environment.json -r har --reporter-har-export api-run.har",
"convert": "har-to-openapi api-run.har > openapi-spec.yaml"
},
"devDependencies": {
"har-to-openapi": "^1.0.0",
"newman": "^6.0.0",
"newman-reporter-har": "^1.2.0"
}
}
```
### ✨ Step 3: Run Your New Build Script\!
That's it. You've built it.
From your terminal, just run your main script:
```bash
npm run generate:spec
```
This command will:
1. **Trigger `npm run newman`**: This runs your collection, uses your environment variables, and saves the live responses to a new file named `api-run.har`.
2. **Trigger `npm run convert`**: This immediately picks up `api-run.har`, converts it, and saves the final output to `openapi-spec.yaml`.
You now have a one-command system for generating an OpenAPI spec from your collection's live responses.
-----
### 💡 Alternative Methods (Good to Know)
While the method above is excellent because it's based on **live data**, there are two other ways to do this that are based on **saved examples** in your collection.
#### Method 1: The `postman-to-openapi` Tool
This is a single tool that converts a Postman collection JSON *directly* to an OpenAPI spec. It doesn't run the requests. Instead, it uses the **saved examples** you have for each request.
1. **Install:** `npm install -g postman-to-openapi`
2. **Run:** `p2o collection.json -f openapi-spec.yaml`
* **Pro:** Very fast. No server required.
* **Con:** The spec is only as good as your saved examples. It doesn't use live responses.
#### Method 2: The Official Postman API
Postman has its own API endpoint that will do this conversion for you on their servers.
1. Find your Collection ID (in Postman, click your collection, go to the "Info" tab (ⓘ), and copy the ID).
2. Get your Postman API Key (from your [Account Settings](https://www.google.com/search?q=https://go.postman.co/settings/me/api-keys)).
3. Run this `curl` command:
```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://api.getpostman.com/collections/YOUR_COLLECTION_ID/transformations" \
| jq ".output" -r > openapi-spec.json
```
* **Pro:** Official Postman conversion.
* **Con:** Also relies on saved examples, not live responses. Requires an internet connection and an API key.
Would you like me to help refine the `package.json` script with more options?