Core: Custom action + ApiDoc

[marcin-piela]

How is proper way to add custom action with custom api documentation?

Now I have custom POST action for confirm user account in users collection "users/confirmation", everything is working ok, but documentation is bad. I want to change "Parameters" and "Return" properties. How to do that? If I add @ApiDoc annotation for custom controller I have double action "users/confirmation", one with my annotation and one with default annotations from user resource.

Maybe something is wrong in DunglasApiProvider, I think there must be some statement for existing ApiDoc annotation in custom controller.

[marcin-piela]

I suggest something like that in DunglasApiProvider in NelmioApiDoc:

if (!$this->operationApiDocExists($operation, $annotationReader)) {
    $annotations[] = $this->getApiDoc(true, $resource, $operation, $resourceHydraDoc, $entrypointHydraDoc);
}   

And method definition:

/**
 * Check if ApiDoc annotation for operation exists
 * @param $operation
 * @param $annotationReader
 * @return bool
 */
private function operationApiDocExists($operation, $annotationReader)
{
    $defaults = $operation->getRoute()->getDefaults();

    list($controllerClass, $controllerMethod) = explode('::', $defaults['_controller']);

    $reflectedMethod = new \ReflectionMethod($controllerClass, $controllerMethod);
    $methodAnnotations = $annotationReader->getMethodAnnotations($reflectedMethod);

    foreach ($methodAnnotations as $annotation) {
        if ($annotation instanceof ApiDoc) {
            return true;
        }
    }

    return false;
}

[dunglas]

Custom actions can be now documented using Swagger UI.

[alex88]

@dunglas how?

[pesseyjulien]

@dunglas could you provide an example for custom documentation with Action/Controller ?