Fix Postman setup instructions with correct variable names #330
Merged
Conversation
Contributor
Author
|
Requested by: Devon White |
Contributor
The original PR fixes the docs that describe the published Postman
collection. While verifying it against the actual generated output, a
chain of pipeline issues surfaced — this commit lands the fixes and
re-aligns the docs.
Pipeline extraction
- scripts/postman/build-collection.mjs with `build` and `publish`
subcommands; package.json exposes `yarn postman:build` /
`yarn postman:publish`
- Workflow collapses from ~80 lines of inline shell to ~30 lines of
orchestration; same code runs locally and in CI
- openapi-to-postmanv2 pinned as a direct devDependency (no global
install needed locally)
Curated examples
- openapi-to-postmanv2's bundled faker reads `example:` (singular) but
ignores OpenAPI 3.1's `examples:` array form, which the spec uses
3,042 times in REST and 864 in compat
- scripts/postman/inline-examples.js: temp-copy preprocessor that
collapses single-element schema-level examples arrays. Multi-element
arrays and existing singular `example:` are preserved
- Source YAML stays 3.1-compliant; only what Postman sees changes
Per-operation security
- Drop `alwaysInheritAuthentication: true` from convert-options.json:
the converter discards per-operation auth helpers when it's set, so
bearer endpoints were getting auth: null and inheriting Basic Auth,
which the server rejects
- After fix: 230 Basic endpoints inherit collection auth, 3 Bearer
endpoints have explicit overrides, 1 public C2C endpoint has noauth
Customer-friendly variable names
- Collection-level Basic Auth references {{project_id}} / {{api_token}}
- Per-request Bearer Auth references {{subscriber_token}}
- All three are pre-declared in .variable[] with descriptions, visible
in the Variables tab where the docs send customers
- subscriber_token is added only to collections that have bearer
endpoints (REST yes, compat no)
REST docs
- Tip callout below the credentials table covering the subscriber_token
flow with a link to the Create Subscriber Token endpoint
- Compat docs unchanged
To republish the live Postman collections, trigger the publish-postman
workflow via workflow_dispatch with force_all=true.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Updates the "Try it in Postman" setup instructions in both REST API and Compatibility API overview pages to reflect the actual variable names in the generated Postman collections.
Why
The docs previously instructed users to set
space,project_id, andauth_tokenin the collection Variables tab, but the Postman collections (generated from OpenAPI specs viaopenapi-to-postmanv2) actually use:space_name— a collection-level variable for the Space subdomainbasicAuthUsername— a request-level auth variable for the Project IDbasicAuthPassword— a request-level auth variable for the API TokenUsers following the old instructions would set the wrong variable names and requests would fail silently.
Changes
fern/products/apis/pages/core/overview.mdx(REST API overview):fern/products/compatibility-api/pages/rest-api/core/overview.mdx(Compatibility API overview):Requested by: Fern Support