Test your OpenAPI implementation with Spectator

For anyone who has built or maintained an API you know how much dedication it takes to keep your documentation complete, easy-to-read, and, most importantly, accurate. It’s common for developers to experience discrepancies between their API documentation and the actual implementation of that API in the code, especially for endpoints with request parameters or varying response codes. These discrepancies can cause issues on your development team because the developers working on your API could inadvertently change a response or payload which can break a downstream client application.

Enter Spectator. Spectator is a package that provides testing methods you can use within your existing Laravel PHPUnit test suites to ensure your OpenAPI Specification documentation and implementation stay in sync.

Here’s an example of how it works…

Let’s say you have a Users.v1.json spec for fetching users, something simple like the following:

This spec defines both the GET and POST methods for the /users URI, with the User resource being represented with just ID, email, and user attributes. Based on that, a controller has been written to serve up a list of users at GET /users, and have the ability to create a new user at POST /users.

In Laravel apps, the functionality of these endpoints are (hopefully) covered with integration or “Feature” tests using the framework’s HTTP test methods. But writing tests to ensure both the request and responses to these endpoints are concretely adhering to your API spec would be very time-consuming.

Instead, you can use Spectator to automatically run tests that will compare both requests and responses with the expected contract.

<?php
 
namespace Tests\Contract;
 
use Spectator\Spectator;
 
class UsersSpecTest extends TestCase
{
    public function setUp(): void
    {
        parent::setUp();
 
        Spectator::using('Users.v1.json');
    }
 
    public function test_validates_valid_json_response()
    {
        $this->getJson('/users')
            ->assertValidRequest()
            ->assertValidResponse(200);
    }
}

This test will pass: all green! The request going in and the response coming out of this endpoint matches what has been defined in the spec. Now just for fun go change a key or value being returned from your /users route and run the test again. Suddenly, it’s broken! Revert that change and instead change something in your spec for GET /users. Again, red alerts.

This is a trivial example but it demonstrates what’s possible with Spectator. Not only can you validate correct requests and responses but incorrect ones, and validate the errors that you expect.

$this->getJson('/users')
    ->assertValidRequest()
    ->assertInvalidResponse(400)
    ->assertValidationMessage('get-users does not match the spec: [ format: {"type":"string","format":"email"} ]');

If you or your team are currently managing an API then give Spectator a try. I think it’s a game-changer when it comes to controlling the discrepancies and breaking changes that are bound to happen between API docs and code, and will help keep both your team and your API consumers happy.