Every API team has the same file: a Postman collection that was correct six months ago. Someone adds an endpoint, nobody updates the collection, and the next person onboarding spends an afternoon guessing URLs and bodies.
OpenAPI solves this, but for many internal Yii2 APIs a full spec is more than the team needs. What people actually use is a collection to click through.
This post shows a smaller approach: describe each endpoint with a few annotations right next to the action, and generate the collection with one command.
Install
composer require --dev iguazoft/yii2-postman-generator The extension registers a postman console command through Yii2's extension bootstrap. There is nothing to configure.
Annotate an action
/** * @Postman\Collection("Shop API") * @Postman\BaseUrl("https://api.shop.test") */ class UserController extends \yii\rest\Controller { /** * @Postman\Request("List users") * @Postman\Folder("Users") * @Postman\Path("/api/users") * @Postman\Query("page", "1") * @Postman\Auth("bearer", "{{token}}") */ public function actionIndex() { /* ... */ } /** * @Postman\Request("Create user") * @Postman\Folder("Users") * @Postman\Method("POST") * @Postman\Path("/api/users") * @Postman\Body({ * "name": "John Doe", * "email": "john@example.com" * }) */ public function actionCreate() { /* ... */ } } Only actions with @Postman\Request are exported, so you can adopt it one endpoint at a time.
Generate
php yii postman/generate The command scans @app/controllers (use --dirs for modules) and writes @app/docs/api.postman_collection.json. Import it in Postman with Import > File. The same file works in Insomnia, Bruno and Hoppscotch, which read the Postman v2.1 format.
What you get:
- Folders from
@Postman\Folder -
{{baseUrl}}and{{token}}collection variables - Query parameters, headers and JSON bodies
- Path variables:
/users/:idor/users/{id} - Bearer, basic and API key auth
Keep it in sync with CI
The collection id is derived from the collection name, so generating twice gives the same file. That means you can commit the JSON and fail the build when someone forgets to regenerate it:
- run: php yii postman/generate - run: git diff --exit-code docs/api.postman_collection.json A pull request that adds an annotated endpoint without regenerating the collection now fails the build.
When to use OpenAPI instead
If you publish a public API, need response schemas, or generate client SDKs, use OpenAPI. This extension is for the common case where the team needs a working collection and nothing more.
Try it
The code is MIT, tested on PHP 7.4 to 8.4: https://github.com/dannyrios81/yii2-postman-generator
If something is missing for your API, open an issue. Reading routes from UrlManager rules is the next idea on the list.

