feat(docs): add Postman button with deep-linking to endpoints #4914
Conversation
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
- Add server-side helper for Postman URL computation with caching - Create PostmanButton component for client-side rendering - Implement fuzzy matching by method+path to find specific Postman requests - Cache collection fetching and endpoint URL computation using unstable_cache Co-Authored-By: Deep Singhvi <[email protected]>
devin-ai-integration
bot
force-pushed
the
devin/1762575195-postman-button
branch
from
e3e406c to
9a15a10
Compare
🌱 Smoke Test PreviewPreview URL: https://smoke-test-preview-5116d364-ce5e-4c01-bdce-8c6bb2fe69dd.docs.buildwithfern.com 🕷️ Smoke Test Crawler ResultsPages crawled: 29 ❌ Pages with Errors
📊 Full error breakdown
See full details in the workflow logs. |
Co-Authored-By: Deep Singhvi <[email protected]>
- Access postmanCollectionUrl from API reference node using findNode - Pass postmanCollectionUrl through component hierarchy to EndpointContent - Compute Postman URL for specific endpoint using getPostmanUrlForEndpoint - Display PostmanButton in PageHeader when postmanUrl is available Co-Authored-By: Deep Singhvi <[email protected]>
- Fix import ordering in ApiEndpointPage.tsx and PostmanButton.tsx - Fix formatting of postmanCollectionUrl ternary - Fix dynamic path segment handling to pass ':' instead of segment value Co-Authored-By: Deep Singhvi <[email protected]>
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContent.tsx
Outdated
Show resolved
Hide resolved
…ts/EndpointContent.tsx Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
| for (const item of items) { | ||
| if (item.request) { | ||
| const id = item.uid || item.id || ""; | ||
| const method = item.request.method.toUpperCase(); |
There was a problem hiding this comment.
Missing safety check for item.request.method before calling .toUpperCase(). If Postman returns a request without a method field, this will crash the server-side rendering with "Cannot read property 'toUpperCase' of undefined".
View Details
📝 Patch Details
diff --git a/packages/fern-docs/bundle/src/server/postman.ts b/packages/fern-docs/bundle/src/server/postman.ts
index a74b38672..626892cd2 100644
--- a/packages/fern-docs/bundle/src/server/postman.ts
+++ b/packages/fern-docs/bundle/src/server/postman.ts
@@ -136,6 +136,10 @@ function flattenRequests(items: PostmanItem[], parentPath: string[] = []): Postm
for (const item of items) {
if (item.request) {
const id = item.uid || item.id || "";
+
+ if (!item.request.method) {
+ continue; // Skip requests without a method
+ }
const method = item.request.method.toUpperCase();
let pathSegments: string[] = [];
Analysis
Runtime crash in flattenRequests() when Postman API returns request without method field
What fails: flattenRequests() in packages/fern-docs/bundle/src/server/postman.ts calls .toUpperCase() on undefined item.request.method, causing "Cannot read properties of undefined (reading 'toUpperCase')" error
How to reproduce:
// Mock Postman collection with missing method field
const collection = {
item: [{
uid: "test",
name: "Test Request",
request: {
// method field missing/undefined
url: "https://example.com/api"
}
}]
};
flattenRequests(collection.item); // Throws TypeErrorResult: Unhandled TypeError crashes server-side rendering. Error occurs outside try-catch block in getPostmanUrlForEndpoint() after successful fetch operation.
Expected: Should gracefully skip requests without method field per Postman Collection Format v2.1.0 schema where method field is optional, not required.
Add Postman button with deep-linking to API endpoint pages
This PR adds an "Open in Postman" button to API endpoint documentation pages that deep-links directly to the specific endpoint within a Postman workspace collection.
What was the motivation & context behind this PR?
Users can now configure a Postman workspace collection URL in their
docs.ymlfile (via thepostmanfield added in previous PRs: #4911, fern#10429, fern#10430). This PR consumes that URL and creates a button on each endpoint page that:Link to Devin run: https://app.devin.ai/sessions/4dc111be363449128486bd5bbcb6628d
Requested by: Deep Singhvi (@dsinghvi)
Implementation Details
Server-side helper (
packages/fern-docs/bundle/src/server/postman.ts)parseWorkspaceCollectionUrl(): Extracts team, workspace, and collection UID from Postman workspace URLscreateFetchCollectionJson(): Fetches collection JSON withunstable_cache()(15-minute TTL)normalizePath(): Normalizes paths by treating dynamic segments ({id},:id,{{var}}) as placeholders (:)flattenRequests(): Recursively flattens nested Postman collection structurematchEndpointToRequest(): Fuzzy matches endpoints by method + path length + literal segment matching (case-insensitive)getPostmanUrlForEndpoint(): Main export that orchestrates the matching and URL generationUI Integration
PostmanButton.tsx: Client component usingFernLinkButtonwith external link iconEndpointContentcomponent'sPageHeaderpostmanCollectionUrlis configured and a matching request is foundData Flow
ApiEndpointPageusesFernNavigation.utils.findNode()to access the API reference node and extractpostmanCollectionUrlApiEndpointPage→ApiEndpointContent→EndpointContentEndpointContentcallsgetPostmanUrlForEndpoint()server-side to compute the specific Postman URLPostmanButtonif URL is successfully computedHow has this PR been tested?
Critical items to test:
postmanCollectionUrlis configuredhttps://www.postman.com/collections/{uid}unstable_cache()works as expected and doesn't cause stale data issuesKnown risks:
{id}vs:idvs{{var}})item.uidanditem.id, but some collections store ID initem.request.idCI Status:
/home/get-started/external-dependency-testwith[error-boundary-fallback]error - this appears unrelated to my changes since it's on a documentation page, not an API endpoint page where the Postman button appears. The smoke test successfully crawled 28/29 pages including multiple API endpoint pages with status 200.Human review checklist: