Skip to content

Polish API collection content for docs generation#1

Merged
roncodes merged 8 commits into
mainfrom
polish-api-collection-content
May 7, 2026
Merged

Polish API collection content for docs generation#1
roncodes merged 8 commits into
mainfrom
polish-api-collection-content

Conversation

@roncodes
Copy link
Copy Markdown
Member

@roncodes roncodes commented May 7, 2026

Summary

Polishes the Native Git Postman collections that feed the generated API reference docs.

This PR:

  • fixes stale and copy-pasted endpoint descriptions
  • normalizes embedded URL query strings into queryParams maps
  • adds .params.yaml and .queryParams.yaml sidecars for docs parameter tables
  • keeps Storefront and Ledger namespace handling explicit through collection-level api_prefix

Fix #1: stale descriptions touched

Fleetbase API:

  • Contacts: Query Contacts
  • Fleets: Query Fleets
  • Orders: Capture QR Code for Order, Capture Signature for Order, Dispatch an Order, Get Order Next Activity, Set Order Destination, Start an Order, Update Order Activity
  • Places: List all Places, Query Places
  • Service Areas: Query Service Areas
  • Tracking Statuses: Update a Tracking Status
  • Zones: Create a Zone, Query Zones, Retrieve a zone

Storefront API:

  • Cart: Add Item to Cart, Empty cart, Remove item from cart, Retrieve a Cart, Retrieve or Create Cart
  • Category: List categories
  • Checkout: Capture checkout as order
  • Customer: Authenticate a Customer, Authenticate a Customer via SMS, Create a Customer, List a customer orders, List a customer saved places, Query customers, Register customer device, Setups a verification request to create a new storefront customer, Update a Customer, Verify a SMS code
  • Delivery Service Quote: Retrieve a Delivery Service Quote
  • Products: Query Products, Retrieve a Product
  • Store Locations: Query Store Locations

Fix #2: query parameter normalization

Moved embedded query strings out of request url fields and into Native Git queryParams maps across 41 request files. A final grep confirmed no url: ...? remains in postman/collections/**/*.request.yaml.

Fix #3: parameter metadata coverage

Added 94 sidecar metadata files:

  • Fleetbase API: create/update request body params and non-trivial query params
  • Fleetbase Core API: create/update request body params and non-trivial query params
  • Fleetbase Ledger API: wallet query params
  • Fleetbase Storefront API: create/update request body params and non-trivial query params
  • Fleetbase Integrated Vendor Flow: workflow form params and query params

Verification

  • pnpm postman:lint
  • node scripts/validate-collections.js
  • YAML parse for postman/collections/**/*.yaml
  • POSTMAN_COLLECTIONS_DIR=/Users/ron/Development/fleetbase/postman/postman/collections node scripts/generate-api-docs.mjs completed successfully from fleetbase.io
  • Spot-checked content/docs/api/fleetbase/places.mdx
  • Spot-checked content/docs/api/storefront/cart.mdx

Note: Postman CLI is not installed locally, so scripts/lint-collections.sh ran the repository validator and skipped Postman CLI schema lint as designed.

@roncodes roncodes merged commit 7600e1c into main May 7, 2026
1 check passed
@roncodes roncodes deleted the polish-api-collection-content branch May 7, 2026 03:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant