enable to assert the swagger documented keys and API response

dev-master 2015-04-09 01:35 UTC


enable to assert swagger 1.2 doc keys and API response. For Swagger 2 take a look to SwaggerAssertions

Build Status Coverage Status



    "require-dev": {
        "gong023/swagger-assert": "dev-master"

requires PHP5.4+


Sample API

Sample API is below. Swagger-assert enables you to assert that /plain response has swagger keys id,name.

 * @SWG\Resource(
 *     resourcePath="plain",
 *     @SWG\Api(
 *         path="/plain",
 *         description="plain api structure",
 *         @SWG\Operation(
 *             method="GET",type="SimpleMember",nickname="plain"
 *         )
 *     )
 * )
 * @SWG\Model(
 *     id="SimpleMember",
 *     @SWG\Property(name="id", type="integer", required=true, description="user id"),
 *     @SWG\Property(name="name", type="string", required=true, description="user name")
 * )
$app->get('/plain', function () use ($app) {
    $response = [
        'id'   => 0,
        'name' => 'kohsaka'

    return $app->json($response);


At first, call SwaggerAssert::analyze at the start of the test. Argument is directory path where annotation file exists.

// testing bootstrap.php

Assert keys

Second, call SwaggerAssert::responseHasSwaggerKeys in test class.

  • First argument: array of API response
  • Second argument: string of http method
  • Third argument: url of API endpoint

When testing the sample API by PHPUnit, code is as follows.

use SwaggerAssert\SwaggerAssert;

class PlainApiTest extends \PHPUnit_Framework_TestCase
    public function testResponseHasSwaggerKeys()
        $response = $this->request('get', '/plain');
        $result = SwaggerAssert::responseHasSwaggerKeys(array $response, 'get', '/plain', $onlyRequired = true);


SwaggerAssert::responseHasSwaggerKeys compares API response keys and keys in swagger doc and return true when they match. If they differs, output below error message.

SwaggerAssert\Exception\CompareException: Failed asserting that API response and swagger document are equal.
--- Response
+++ Swagger
@@ @@
 Array (
-    0 => 'id'
-    1 => 'name'
+    0 => 'name'

The fourth argument is optional. If you give false, responseHasSwaggerKeys contains required=false keys to assert. Default value is true.

if you need more sample, please take a look at swagger-assert-sandbox.


Swagger doc and API response sometimes differ. If they differ, the swagger doc causes confusion in development. So create library to assert API response and swagger doc.

Bugs & Contributions

Please report bugs by opening an issue.

Contributions are welcome.