API Plateform : Améliorer la doc de votre API

Lors du précédent Symfony Pot du 25 février, nous vous avons présenté le framework API Platform dédié à la création d’API REST.

Lorsqu’on travaille en équipe ou pour faciliter la maintenance de son API, il est nécessaire de documenter les routes disponibles d’une API. La difficulté est que certaines de ces routes sont gérées par des dépendances externes pour lesquelles il n’est pas possible d’ajouter facilement des annotations ApiDoc. Par exemple pour une authentification à l’aide des bundles FOSUserBundle et LexikJWTAuthenticationBundle, la route login_check accessible n’est pas documentée et il n’est pas possible de facilement ajouter une annotation ApiDoc comme on le ferait sur nos propres controller. Comme nous avions pu le voir durant la présentation (https://github.com/acseo/my-running-planner/tree/5-document-external-dependencies), il est possible de créer son propre Provider d’annotations afin de fournir des annotations construites en dehors de ses controlleurs. Ce service peut être retrouvé ici : https://github.com/acseo/my-running-planner/blob/5-document-external-dependencies/src/ACSEO/Bundle/MyRunningPlannerBundle/Service/NelmioApiYmlProvider.php ou ci-dessous :

namespace ACSEOBundleMyRunningPlannerBundleService;
use NelmioApiDocBundleAnnotationApiDoc;
use NelmioApiDocBundleExtractorAnnotationsProviderInterface;
use SymfonyComponentFinderFinder;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingRoute;
use SymfonyComponentYamlYaml;
/**
 * Generate annotations for vendor routes to be displayed in Nelmio ApiDoc.
 */
class NelmioApiYmlProvider implements AnnotationsProviderInterface
{
    private $rootDir;
    public function __construct($rootDir)
    {
        $this->rootDir = $rootDir;
    }
    /**
     * {@inheritdoc}
     */
    public function getAnnotations()
    {
        $annotations = [];
        $configDirectories = array($this->rootDir.'/config/apidoc');
        $finder = new Finder();
        $finder->files()->in($configDirectories);
        if (count($finder) == 0) {
            throw new NotFoundHttpException('No file found for this protocol');
        }
        foreach ($finder as $file_) {
            $data = Yaml::parse(file_get_contents($file_));
            $vendors = array_keys($data);
            foreach ($vendors as $vendor) {
                $apiDoc = new ApiDoc($data[$vendor]);
                $route = new Route(
                    $data[$vendor]['route']['path'],
                    $data[$vendor]['route']['defaults'],
                    $data[$vendor]['route']['requirements'],
                    $data[$vendor]['route']['options'],
                    $data[$vendor]['route']['host'],
                    $data[$vendor]['route']['schemes'],
                    $data[$vendor]['route']['methods'],
                    $data[$vendor]['route']['condition']
                );
                $apiDoc->setRoute($route);
                $apiDoc->setResponse($data[$vendor]['response']);
                $annotations[] = $apiDoc;
            }
        }
        return $annotations;
    }
}

et il est déclaré avec le tag nelmio_api_doc.extractor.annotations_provider qui lui permet d’être appelé par le Bundle ApiDoc.

<service id="nelmio_api_doc.yml_provider.acseo_yml_provider" class="%nelmio_api_doc.yml_provider.acseo_yml_provider.class%">
        <argument>%kernel.root_dir%
        <tag name="nelmio_api_doc.extractor.annotations_provider" />
    </service>

On peut alors documenter une nouvelle route (par exemple le login_check) de la façon suivante :

// app/config/apidoc/lexik_jwt_authentication.yml
login_check:
    requirements: []
    views: []
    filters: []
    parameters:
        _password:
            dataType: string
            required: true
            name: _password
            description: Password
            readonly: false
        _username:
            dataType: string
            required: true
            name: _username
            description: Username
            readonly: false
    input: null
    output: null
    link: null
    description: "Get JWT token for logged user"
    section: "Session"
    documentation: null
    resource: null
    method: "POST"
    host: ""
    uri: "/login_check"
    response:
        token:
            dataType: string
            required: true
            description: JWT token
            readonly: true
    route:
        path: /login_check
        defaults:
            _controller: FOSUserBundleControllerSecurityController::checkAction
        requirements: []
        options:
            compiler_class: SymfonyComponentRoutingRouteCompiler
        host: ''
        schemes: []
        methods: [ 'POST' ]
        condition: ''
    https: false
    authentication: false
    authenticationRoles: []
    cache: null
    deprecated: false
    statusCodes: []
    resourceDescription: null
    responseMap: []
    parsedResponseMap: []
    tags: []

Vous avez maintenant votre route login_check documentée et utilisable depuis la sandbox.

Utilisation du context hydra pour décrire ses routes API

private function getOperationHydraDoc($method, array $hydraDoc, $context = null)
{
    $contextTitle = isset($context['hydra:title']) ? $context['hydra:title'] : null;
    foreach ($hydraDoc['hydra:supportedOperation'] as $supportedOperation) {
        $operationTitle = isset($supportedOperation['hydra:title']) ? $supportedOperation['hydra:title'] : null;
        if ($supportedOperation['hydra:method'] === $method and ($contextTitle == null or $contextTitle === $operationTitle)) {
            return $supportedOperation;
        }
    }
}

resource.user.collection_operation.cpost:
        class:     "DunglasApiBundleApiOperationOperation"
        public:    false
        factory:   [ "@api.operation_factory", "createCollectionOperation" ]
        arguments:
            -    "@resource.user"
            -    [ "POST" ]
            -    "/users"
            -    "AcseoCoreBundle:User:cpost"
            -    "api_users_post"
            -    # Context (will be present in Hydra documentation)
                 "@type":       "hydra:Operation"
                 "hydra:title": "Creates a User Resource."
                 "returns":     "xmls:string"
                 "statusCodes":
                    201: [ 'Resource created' ]
                    400: [ 'Data is invalid' ]

   private function getApiDoc(
    ...
    )
    ...
    $statusCodes = isset($operation->getContext()['statusCodes']) ? $operation->getContext()['statusCodes'] : [];
    $data = [
        'resource' => $route->getPath(),
        'description' => $operationHydraDoc['hydra:title'],
        'resourceDescription' => $resourceHydraDoc['hydra:title'],
        'section' => $resourceHydraDoc['hydra:title'],
        'statusCodes' => $statusCodes,
    ];
    ...