Support resolving response schema's from request path directly

[beblife]

Hello! 👋

Recently stumbled on an idea when working with a very specific setup that might be worth supporting.
This seemed like a good place to post my thoughts instead of a PR.

Context

// spec.json
{
    "openapi": "3.0.0",
    "info": {
        "title": "My API",
        "version": "1.0",
        "description": "My example API"
    },
    "paths": {
        "/users/me": {
            "get": {
                "operationId": "get-current-user",
                "summary": "Retrieve current user",
                "description": "Retrieve user associated with the transmitted access token.",
                "tags": [
                    "Current user"
                ],
                "security": [
                    {
                        "User access token": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Unauthenticated"
                    }
                }
            }
        },
        "/users/{user}": {
            "parameters": [
                {
                    "schema": {
                        "type": "string"
                    },
                    "name": "user",
                    "in": "path",
                    "required": true,
                    "examples": {
                        "Normal reference": {
                            "value": "123",
                            "summary": "Standard identifier"
                        },
                        "Current user alias": {
                            "value": "me",
                            "summary": "Special convenience identifier",
                            "description": "Always resolves to user associated with the transmitted access token"
                        }
                    },
                    "description": "The unique identifier for a user."
                }
            ],
            "get": {
                "operationId": "get-user",
                "summary": "Retrieve a user",
                "description": "Retrieve a specific user.",
                "tags": [
                    "Users"
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                }
            }
        }
    }
}

// app/Providers/RouteServiceProvider.php:boot()

Route::model('user', User::class, function ($value) {
    if ($value !== 'me') {
        return false;
    }

    $guard = Auth::guard('api');

    if ($guard->check()) {
        return $guard->user();
    }

    throw new AuthenticationException('Unauthenticated.', [$guard]);
});

// routes/api.php

Route::prefix('/users/{user}')->group(function () {
    Route::get('/', ShowUserRequestHandler::class);
    Route::get('/profile', ShowUserProfileRequestHandler::class);
});

When writing a test for the /users/me endpoint for the 401 status code with the Spectator middleware active the response validator will always resolve the path item for /users/{user}. This is because the special case for /users/me is not defined in the routes file and the package response validator uses $request->route()->uri() to find the path item.

// tests/Feature/UserTestCase.php


public function test_the_special_me_alias_requires_authentication()
{
    Spectator::using('spec.json');

    $response = $this->getJson('/users/me'/);

    $response->assertValidRequest()
    $response->assertValidResponse(401); 
}

Current possible solution

This can be solved by updating the spec.json to drop the path for users/me and add the 401 status code along with the security schema to the users/{user} path. This however might cause confusion for clients interacting with the API that the users/{user} endpoint always requires authentication, which is not always the case.

The idea

Resolve the path item from the specification file using the $request->path() first and fall back to the current $request->route()->uri() implementation when nothing is found. This approach would make the test in the context section pass, as it resolves the correct path item, without any changes to the routes setup.

I created a branch on my fork with a test that replicates this setup in a simplified way and updated the middleware to support this idea to demonstrate the idea.

Happy to hear your thoughts on this!

[jarrodparkes]

@beblife I'm not sure I have a strong enough opinion about uri versus path to weigh in, but I can offer this comment on we've implemented Spectator-based tests: In practice, we only test 2xx requests/responses against the spec since most of the error responses (in our case, from Laravel) follow some standard structure and/or include context-specific keys that we don't try describe using our spec.

[beblife]

@jarrodparkes Thank you for the input first of all. I can get behind the reasoning that testing only the 2xx responses against a spec and relying on framework (Laravel in this case) response structures for other use cases is a very valid approach.

However looking at it from a documentation perspective this could possibly lead to a situation where some responses remain undocumented in the spec. To give you some context: Usually we (at work) design the API upfront using the OpenAPI spec and use this package to ensure we're staying true to whatever was documented (and agreed upon) in that specification when implementing. This often includes testing unhappy paths where a specific 4xx response code should be returned. That's just how we make use of the package and it's been working great so far.

The example I started this discussion with still holds up even when testing only 2xx responses. When both the paths are defined in the spec but configured in a specific way in the code to work , it would currently always resolve /users/{user} even when making a request to /users/me. In theory, both could have a different response schema and result in failing tests for the wrong reasons. Resolving from the URI first and falling back to the defined paths in Laravel could help cover this scenario.

Happy to hear your feedback on this!

[jarrodparkes]

Hey @beblife reading again through this now. I'm following your explanation better the second time through 👍!

Your idea sounds reasonable to me. I know less about Laravel's route support and if there is a way to achieve defining /users/me and /users/{user} (the generic case) in a routes file. Assuming there isn't, then I understand where you are coming from.

I'd be curious to hear @hotmeteor thoughts on this.