Terminal
Terminal/Skill
Generates API documentation from a Postman collection or OpenAPI spec that you can share with teammates.
By Postman
Works with
npx skills add postmanlabs/postman-plugin --skill api-documentationThe bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.
When working on any API task, the first step is to establish and capture the contract. API documentation can be done in two predominant ways:
It is recommended to create both. They serve different, complementary use cases, and the Postman CLI can generate one from the other. Use the artifact that represents the current source of truth rather than recreating its operations by hand. Postman collections are human-friendly and enable other capabilities such as mocks, monitors, SDKs, and specifications. Collections created or edited directly on disk use the v3 format described by collection-schema-v3.
Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.
When an OpenAPI specification already defines the contract, generate a Postman collection from it in one command:
postman spec generate collection <spec-path-or-id> -n "<collection-name>"
See reference/rest-api-best-practices.md for the practices well-documented APIs tend to already follow: resource naming, HTTP method/status-code usage, error response shape, versioning, pagination, filtering, auth, idempotency, and backward compatibility. A spec or collection that already follows these renders documentation with nothing left to fix.
Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
postman spec generate collection instead of manually duplicating its
operations.