Search by

iguazoft / yii2-postman-generator

dannyrios81

Generate Postman collections (v2.1) from PHPDoc annotations in your Yii2 controllers. Works with Insomnia, Bruno and Hoppscotch too.

Package info

github.com/dannyrios81/yii2-postman-generator

Type:yii2-extension

pkg:composer/iguazoft/yii2-postman-generator

Statistics

Installs: 11

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.2.0 2026-11-19 17:57 UTC

This package is auto-updated.

Last update: 2026-11-19 17:59:30 UTC


README

tests Latest Stable Version Total Downloads PHP License

Keep your Postman collection in sync with your Yii2 API. Annotate your controller actions, run one command, and import the result into Postman, Insomnia, Bruno or Hoppscotch.

No OpenAPI spec to write and maintain, no extra dependencies: only Yii2.

Leer en español

Annotate your controllers, run one command, get a Postman collection

/**
 * @Postman\Request("Create user")
 * @Postman\Folder("Users")
 * @Postman\Method("POST")
 * @Postman\Path("/api/users")
 * @Postman\Auth("bearer", "{{token}}")
 * @Postman\Body({"name": "John Doe", "email": "john@example.com"})
 * @Postman\Test("status", "201")
 * @Postman\Test("json", "data.id")
 */
public function actionCreate() { /* ... */ }
$ php yii postman/generate
Scanning:
  - /var/www/app/controllers

✓ 12 request(s) written to /var/www/app/docs/api.postman_collection.json

See a full generated file in docs/example.postman_collection.json.

Why

  • The docs live next to the code. When you change an endpoint, the annotation is right there.
  • One command, repeatable. Run it in CI and commit the JSON, so the collection never drifts.
  • Postman Collection v2.1. It imports into Postman, Insomnia, Bruno, Hoppscotch and anything else that reads that format.
  • Lightweight. Unlike Swagger/OpenAPI tooling, you only describe what a client needs to call the endpoint.

Installation

composer require --dev iguazoft/yii2-postman-generator

The extension registers the postman console command automatically through Yii2's extension bootstrap. Nothing to configure.

Usage

1. Annotate your controllers

<?php

namespace app\controllers;

use yii\rest\Controller;

/**
 * @Postman\Collection("Shop API")
 * @Postman\Description("Public API used by the mobile app")
 * @Postman\BaseUrl("https://api.shop.test")
 * @Postman\Variable("apiVersion", "v1")
 */
class UserController extends Controller
{
    /**
     * @Postman\Request("List users")
     * @Postman\Folder("Users")
     * @Postman\Path("/api/users")
     * @Postman\Auth("bearer", "{{token}}")
     * @Postman\Query("page", "1")
     * @Postman\Query("per-page", "20")
     */
    public function actionIndex() { /* ... */ }

    /**
     * @Postman\Request("View user")
     * @Postman\Folder("Users")
     * @Postman\Path("/api/users/{id}")
     */
    public function actionView($id) { /* ... */ }
}

Only actions with @Postman\Request are exported.

2. Generate

php yii postman/generate
Option Alias Default Description
--output -o @app/docs/api.postman_collection.json Output file. Yii aliases allowed.
--dirs -d @app/controllers Comma separated directories, scanned recursively.
--name -n @Postman\Collection or API Collection Collection name.
--base-url -u @Postman\BaseUrl or http://localhost Value of {{baseUrl}}.
--include-hidden -a false Also export actions marked @Postman\Hidden.
php yii postman/generate -d=@app/modules/api/v1/controllers,@app/modules/api/v2/controllers -o=@app/docs/api.json
php yii postman/help   # annotation reference

3. Import

In Postman: Import → File → api.postman_collection.json. Set token in the collection variables and you are ready.

Annotation reference

Class level

Annotation Description
@Postman\Collection("Name") Collection name. The first one found wins.
@Postman\Description("Text") Collection description.
@Postman\BaseUrl("https://api.example.com") Default value of {{baseUrl}}.
@Postman\Variable("key", "value") Collection variable. Repeatable.
@Postman\Test(...) Test applied to every action of the controller. See Tests.

Action level

Annotation Description
@Postman\Request("Name") Required. Request name.
@Postman\Method("POST") HTTP method. Default GET.
@Postman\Path("/api/users/:id") Path. :id and {id} become Postman path variables.
@Postman\Folder("Users") Folder to group the request in.
@Postman\Description("Text") Request description.
@Postman\Auth("bearer", "{{token}}") Bearer token.
@Postman\Auth("basic", "{{user}}", "{{pass}}") Basic auth.
@Postman\Auth("apikey", "X-Api-Key", "{{apiKey}}") API key header.
@Postman\Body({...}) JSON body. Can span several lines.
@Postman\Header("key", "value") Request header. Repeatable.
@Postman\Query("key", "value") Query parameter. Repeatable.
@Postman\Hidden Not exported unless --include-hidden.
@Postman\Test(...) Test script assertion. Repeatable. See Tests.

Arguments can use double quotes, single quotes, or no quotes. Quoted values may contain commas and parentheses. Escape a quote inside a quoted value with a backslash: "John \"Johnny\" Doe".

Tests

@Postman\Test adds assertions to the request's Tests script, so the collection checks your API, not only calls it. Postman runs them after each request; Newman runs them in CI.

Annotation Generated assertion
@Postman\Test("status", "201") Status code is 201.
@Postman\Test("json", "data.id") The JSON body has data.id (dot path, items[0].id works too).
@Postman\Test("json", "data.active", "true") ... and it equals true. Valid JSON (true, 42, null, "42", [1,2]) keeps its type; anything else is compared as a string.
@Postman\Test("header", "Content-Type") The response has the header.
@Postman\Test("header", "X-Api-Version", "2") ... with this exact value.
@Postman\Test("time", "500") Response time is below 500 ms.
@Postman\Test("contains", "created") The body text contains the string.

Tests on the class apply to every action of that controller; action tests are added after them. An action status or time test replaces the class one, so a controller can expect 200 while its actionCreate expects 201.

/**
 * @Postman\Test("status", "200")
 * @Postman\Test("header", "Content-Type", "application/json; charset=UTF-8")
 */
class UserController extends Controller
{
    /**
     * @Postman\Request("Create user")
     * @Postman\Method("POST")
     * @Postman\Path("/api/users")
     * @Postman\Test("status", "201")
     * @Postman\Test("json", "data.id")
     * @Postman\Test("time", "500")
     */
    public function actionCreate() { /* ... */ }
}

Generated script for Create user:

pm.test("Header Content-Type is application/json; charset=UTF-8", function () { pm.response.to.have.header("Content-Type", "application/json; charset=UTF-8"); });
pm.test("Status code is 201", function () { pm.response.to.have.status(201); });
pm.test("Response has data.id", function () { pm.expect(pm.response.json()).to.have.nested.property("data.id"); });
pm.test("Response time is below 500 ms", function () { pm.expect(pm.response.responseTime).to.be.below(500); });

A typo (@Postman\Test("statuss", "200")) or a missing value stops the command with the controller and action name and exit code 65, so CI fails instead of exporting a collection without the test.

Programmatic use

use iguazoft\postman\PostmanGenerator;

$generator = new PostmanGenerator([
    'scanDirs' => ['@app/controllers', '@app/modules/api/controllers'],
    'collectionName' => 'My API',              // optional, overrides @Postman\Collection
    'variables' => ['baseUrl' => 'https://api.example.com'],
    'includeHidden' => false,
]);

$generator->generate('@app/docs/api.postman_collection.json'); // write a file
$json = $generator->generateJson();                           // or get the JSON
$array = $generator->generateArray();                         // or the array

Keep it in sync with CI

# .github/workflows/postman.yml
- run: php yii postman/generate -o=@app/docs/api.postman_collection.json
- run: git diff --exit-code docs/api.postman_collection.json || (echo "Run php yii postman/generate and commit the result" && exit 1)

Run the @Postman\Test assertions against a test server with Newman:

# .github/workflows/api-tests.yml (after starting your API on port 8080)
- run: php yii postman/generate -o=@app/docs/api.postman_collection.json
- run: npx newman run docs/api.postman_collection.json --env-var "baseUrl=http://localhost:8080" --env-var "token=${{ secrets.API_TEST_TOKEN }}"

Requirements

  • PHP 7.4 to 8.4
  • Yii 2.0

Contributing

Issues and pull requests are welcome.

composer install
composer test

License

MIT. See LICENSE.