Skip to content

feat(scripts): add Postman collection generation to project setup - #112

Merged
PAMulligan merged 1 commit into
mainfrom
59-add-postman-collection-generation-to-setup-projectsh
Jun 11, 2026
Merged

feat(scripts): add Postman collection generation to project setup#112
PAMulligan merged 1 commit into
mainfrom
59-add-postman-collection-generation-to-setup-projectsh

Conversation

@PAMulligan

Copy link
Copy Markdown
Contributor

Summary

Implements #59 -- new projects ship with a ready-to-import Postman collection, and the docs script keeps the collection in sync with the OpenAPI spec.

setup-project.sh

Generates three new artifacts in every project (both platforms, dry-run aware):

  • postman/collection.json -- Postman Collection v2.1 with the required structure:
    • Health folder: GET {{base_url}}/health (with a status-200 test) and GET {{base_url}}/ -- both work immediately against the starter app
    • Auth folder: POST {{base_url}}/auth/login placeholder whose test script captures token from a successful login into the auth_token environment variable
    • Resources folder: empty, documented as the landing spot for generated CRUD endpoints
    • Collection-level pre-request script that injects Authorization: Bearer {{auth_token}} on every request once the token is set
    • Collection variables base_url / auth_token as fallbacks when no environment is selected
  • postman/environment.json -- local environment with base_url (platform-aware: http://localhost:3000 for Node, http://localhost:8787 for Workers) and auth_token (type secret so Postman masks it)
  • README.md -- project README with quickstart plus Postman import steps and the regeneration command

generate-openapi-docs.sh

  • Tags the starter spec endpoints with Health so folder-by-tags conversion mirrors the starter collection layout
  • After writing the spec, regenerates postman/collection.json from it via openapi-to-postmanv2 (folderStrategy=Tags), then post-processes the output: renames the converter'''s {{baseUrl}} to Nerva'''s {{base_url}}, restores the base_url/auth_token variables, and re-applies the auth pre-request script the converter cannot know about
  • Conversion failure degrades to a warning -- the spec generation flow is unaffected

Verification

  • bash -n and ShellCheck v0.11.0 (--severity=warning, matching CI) clean on both scripts
  • Full e2e run of setup-project.sh (Node platform): both JSON files parse, folder/variable/script structure asserted with node, README fences and platform substitutions render correctly
  • Full e2e run of generate-openapi-docs.sh inside the generated project: OpenAPI 3.1 spec converts successfully, {{baseUrl}} fully normalized, Health folder produced from tags, auth injection present in the regenerated collection
  • Cloudflare variant verified via --dry-run flow

Closes #59

🤖 Generated with Claude Code

setup-project.sh now generates postman/collection.json (Health, Auth,
Resources folders, base_url/auth_token variables, collection-level
pre-request script that injects the bearer token), a platform-aware
postman/environment.json (port 3000 for Node, 8787 for Workers), and a
project README with import and regeneration instructions.

generate-openapi-docs.sh now tags the starter spec endpoints and, after
exporting the spec, regenerates the Postman collection from it via
openapi-to-postmanv2, then re-applies the base_url/auth_token variables
and the auth pre-request script the converter cannot know about.

Closes #59

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@PAMulligan PAMulligan linked an issue Jun 11, 2026 that may be closed by this pull request
6 tasks
@github-actions github-actions Bot added the area: scripts Automation scripts label Jun 11, 2026
@PAMulligan PAMulligan self-assigned this Jun 11, 2026
@PAMulligan PAMulligan moved this from Todo to Done in PMDS Open Source Roadmap Jun 11, 2026
@PAMulligan
PAMulligan merged commit cf8e8a5 into main Jun 11, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: scripts Automation scripts

Projects

Development

Successfully merging this pull request may close these issues.

Add Postman collection generation to setup-project.sh

1 participant