Can the endpoint documentation be overwritten?

[WardVandevoort]

I have overwritten the update password route and added my own controller so I could add a confirm_password parameter. So instead of only needing to fill in the password you now need to fill in:

{ "password": "string", "confirm_password": "string" }

I would now like to overwrite the existing endpoint documentation so I can add this new parameter like this, but I can't figure out how.

I have checked the documentation and the issues, but I can't really find anything about overwriting the documentation. Is there currently a way to do something like this?

Thanks in advance, Ward

[vincentchalamon]

Hi @WardVandevoort,

This bundle decorates the OpenApiFactory from API Platform (api_platform.openapi.factory) to document the its routes.

For your use-case, I advise you to decorate it too and add your own behavior: https://github.com/coopTilleuls/CoopTilleulsForgotPasswordBundle/blob/main/src/Bridge/ApiPlatform/OpenApi/AbstractOpenApiFactory.php

[vincentchalamon]

Closing as it's not a bug nor related to this bundle, and a solution has been found.

[WardVandevoort]

@vincentchalamon That's what I did, yet it is still showing the original documentation. How am I supposed to make my decorator overwrite the package's decorator?

public function __construct(private OpenApiFactoryInterface $decorated)
{
}

/**
 * @psalm-suppress PossiblyNullReference
 */
public function __invoke(array $context = []): OpenApi
{
    $openApi = ($this->decorated)($context);
    $schemas = $openApi->getComponents()->getSchemas();

    $schemas['ForgotPassword:reset'] = new \ArrayObject([
        'type' => 'object',
        'properties' => [
            'password' => [
                'type' => 'string',
                'example' => 'password',
            ],
            'confirm_password' => [
                'type' => 'string',
                'example' => 'password',
            ],
        ],
    ]);

    $pathItem = new Model\PathItem(
        ref: 'ForgotPassword',
        post: new Model\Operation(
            parameters: [new Model\Parameter(
                name: 'tokenValue',
                in: 'path',
                description: 'Token value',
                required: true,
            )],
            operationId: 'postForgotPasswordToken',
            tags: ['Forgot password'],
            responses: [
                204 => [
                    'description' => 'Email address format valid, no matter if user exists or not',
                 ],
                400 => [
                    'description' => 'Missing password parameter',
                ],
                404 => [
                    'description' => 'Token not found',
                ],
            ],
            summary: 'Validates token test',
            requestBody: new Model\RequestBody(
                description: 'Reset password',
                content: new \ArrayObject([
                    'application/json' => [
                        'schema' => [
                            '$ref' => '#/components/schemas/ForgotPassword:reset',
                        ],
                    ],
                ]),
            )
        )
    );
    $openApi->getPaths()->addPath('/api/users/password-reset/{tokenValue}', $pathItem);

    return $openApi;
}