How miguel-higorre-ch/swagger2postman-ai-cli works
1. Repository purpose
- This is a Node.js/TypeScript CLI that converts a Swagger/OpenAPI document into a Postman collection.
- The core pipeline is: read API spec from a URL → transform it into Postman v2.1.0 JSON → enrich some requests with Gemini AI → write the collection to disk.
2. Top-level structure
- The repo is very small and centered around three source modules in src/:
- index.ts for CLI entrypoint and orchestration
- fetcher.ts for pulling the Swagger/OpenAPI document
- gemini.ts for AI-assisted transformation
- The .js, .d.ts, and .map files alongside the .ts sources indicate the project is compiled TypeScript distributed as JavaScript plus type declarations.
3. CLI boundary
- src/index.ts is the main external interface.
- It likely parses command-line arguments such as --url and --output, then coordinates the rest of the flow.
- This is the boundary between the user and the internal transformation pipeline.
4. Spec ingestion subsystem
- src/fetcher.ts is responsible for getting the Swagger/OpenAPI JSON from a remote endpoint.
- This subsystem is a simple network fetch layer, separate from transformation logic.
- The README implies the tool expects a JSON API docs URL, not a local file-based parser.
5. Transformation subsystem
- The main business logic is the conversion from Swagger/OpenAPI operations into Postman collection objects.
- The README indicates the output is structured by tags, which means the transformation groups endpoints into collections/folders based on API metadata.
- This is where request shape, URL templating, test scripts, and collection layout are assembled.
6. AI enrichment boundary
- src/gemini.ts isolates the Gemini integration.
- Its role is not to replace the converter, but to enhance generated requests with smarter validation, structure, and test script generation.
- This keeps AI-specific behavior behind a dedicated module so the rest of the CLI can remain deterministic.
7. Output artifact
- The final artifact is a Postman Collection v2.1.0 JSON file.
- The tool is designed for downstream execution in Postman or Newman, so the generated JSON is the primary integration point with the rest of the ecosystem.
8. Test script generation
- The generated collections include Postman test scripts using pm.test.
- The README calls out checks for:
- status codes
- response structure
- latency/performance
- This means the architecture includes a testing layer embedded into the collection output, not a separate test runner.
9. Auth/token handling
- There is explicit logic for token management around /login or /auth endpoints.
- Architecturally, this suggests the transformer detects auth-related operations and propagates tokens into later requests so the collection is runnable end-to-end.
- This is an important data flow because it links one generated request’s response to other requests’ variables.
10. Configuration and secrets
- .env.example shows the only clearly external secret/config dependency: GEMINI_API_KEY.
- This means Gemini integration is opt-in via environment configuration, while the Swagger URL and output path come from CLI arguments.
- The configuration boundary is split between env vars and command-line inputs.
11. Runtime and tooling
- The project targets Node.js v18+ and is written in TypeScript.
- The README mentions running via ts-node, which suggests the CLI can be executed directly from source during development.
- package-lock.json indicates npm is the package manager and dependency lock is committed.
12. Likely internal data flow
- The important architecture flow is:
- CLI args parsed in index.ts
- Swagger spec fetched in fetcher.ts
- OpenAPI paths/operations transformed into Postman structure
- Gemini-assisted enhancement applied where needed
- collection JSON serialized to the requested output file
- No database, queue, or persistent service is present; the app is a stateless single-run converter.
13. External services
- The only external AI service visible from the repo is Gemini API.
- Swagger/OpenAPI input is consumed over HTTP from a user-supplied URL.
- The generated collection is intended for Newman execution, which is downstream tooling rather than a runtime dependency.
14. Diagram guidance
- A good architecture diagram should show three main boxes:
- CLI Orchestrator
- Swagger Fetcher
- Gemini Enricher
- Then show outputs to:
- Postman Collection JSON
- optionally Newman/Postman runtime
- The main dependency arrows should emphasize that the CLI coordinates both network fetching and AI enrichment, while the conversion remains local and file-based.
Main entry points: index.ts Converter · gemini.ts Gemini enricher · fetcher.ts Spec fetch
Components 16
CLI flow
User-facing command entrypoint and orchestration
- CLI entry · Parses args and starts the conversion run
src/index.ts - Orchestrator · Coordinates fetch, conversion, enrichment, and write steps
src/index.ts - Arg parsing · Accepts Swagger URL, output path, and runtime options
src/index.ts
Conversion core
Spec ingestion, transformation, and AI enrichment
- Spec fetch · Retrieves Swagger/OpenAPI JSON from a remote URL
src/fetcher.ts - OpenAPI spec · Fetched API description used as conversion source
- Converter · Transforms operations into Postman v2.1.0 collection structure
src/index.ts - Tag grouping · Organizes requests and folders by API tags
- Auth handling · Detects login or auth endpoints and propagates tokens
- Test scripts · Embeds checks for status, structure, and latency
- Gemini enricher · Optional AI-assisted request refinement and script generation
src/gemini.ts - Gemini API · LLM service used through environment configuration
Outputs
Generated artifacts and downstream consumers
- Collection JSON · Serialized Postman collection written to disk
- Output file · User-specified destination for the generated collection
- Postman/Newman · Consumes the generated collection for execution
- Node.js 18+ · Execution environment for the CLI
- TypeScript build · Distributed as JS, declarations, and sourcemaps
Connections 17
- CLI entry → Arg parsing: reads · CLI entry parses command-line inputs
- CLI entry → Orchestrator: starts · Entrypoint hands control to the orchestrator
- Orchestrator → Spec fetch: fetches · Coordinator loads the remote API spec
- Spec fetch → OpenAPI spec: returns · Fetcher yields the OpenAPI document
- Orchestrator → Converter: converts · Orchestrator invokes the collection builder
- OpenAPI spec → Converter: source · Spec data becomes Postman output
- Converter → Tag grouping: organizes · Requests are grouped by tags
- Converter → Auth handling: applies · Auth-aware logic wires token flow between requests
- Converter → Test scripts: embeds · Generated requests include Postman test scripts
- Orchestrator → Gemini enricher: enriches · Coordinator optionally calls Gemini for smarter output
- Gemini enricher → Gemini API: requests · Gemini module communicates with the external AI service
- Gemini enricher → Converter: refines · AI output feeds back into request shaping and scripts
- Converter → Collection JSON: serializes · Collection is emitted as Postman v2.1.0 JSON
- Collection JSON → Output file: writes · Generated JSON is persisted to the requested file
- Output file → Postman/Newman: consumed by · Artifact is used in Postman or Newman
- CLI entry → Node.js 18+: runs on · CLI executes in a Node.js 18+ environment
- CLI entry → TypeScript build: built from · Source is compiled and distributed as JS plus typings