Responses

In order to create response use this Artisan command:

php artisan openapi:make-response ListUsers

This will create ResponseFactory object which you may use to construct a response:

class ListUsersResponse extends ResponseFactory
{
    public function build(): Response
    {
        return Response::ok()->description('Successful response');
    }
}

Finally, add Response attribute with factory name to your route:

use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * List users.
    */
    #[OpenApi\Operation]
    #[OpenApi\Response(factory: ListUsersResponse::class)]
    public function index(User $user)
    {
        //
    }
}

Reusable responses

Responses can be reusable. Adding Vyuldashev\LaravelOpenApi\Contracts\Reusable will indicate that it should be added to components/responses section and reference will be used instead of response definition. This can be handy for validation errors object:

use Vyuldashev\LaravelOpenApi\Contracts\Reusable;

class ErrorValidationResponse extends ResponseFactory implements Reusable
{
    public function build(): Response
    {
        $response = Schema::object()->properties(
            Schema::string('message')->example('The given data was invalid.'),
            Schema::object('errors')
                ->additionalProperties(
                    Schema::array()->items(Schema::string())
                )
                ->example(['field' => ['Something is wrong with this field!']])
        );

        return Response::create('ErrorValidation')
            ->description('Validation errors')
            ->content(
                MediaType::json()->schema($response)
            );
    }
}

And in controller's method:

use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Create user.
    */
    #[OpenApi\Operation]
    #[OpenApi\Response(factory: ErrorValidationResponse::class, statusCode: 422)]
    public function store(Request $request)
    {
        //
    }
}

Multiple responses

You can use multiple responses on a single controller method (for example, success, not found, and validation errors).

Even if the schema defines a status code, you must supply the status code in the controller method attributes, or only one response will be included in the result.

Example:

use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Create user.
    */
    #[OpenApi\Operation]
    #[OpenApi\Response(factory: CreatedUserResponse::class, statusCode: 201)]
    #[OpenApi\Response(factory: ErrorUnauthenticatedResponse::class, statusCode: 401)]
    #[OpenApi\Response(factory: ErrorForbiddenResponse::class, statusCode: 401)]
    #[OpenApi\Response(factory: ErrorNotFoundResponse::class, statusCode: 404)]
    #[OpenApi\Response(factory: ErrorValidationResponse::class, statusCode: 422)]
    public function store(Request $request)
    {
        //
    }
}