Document integration with NelmioApiDoc

[b-durand]

Hello,

it would be nice to add a page in doc for the integration with NelmioApiDoc: documentation for token method ans OAuth in sandbox.

Thanks in advance.

[BraisGabin]

Related: https://github.com/nelmio/NelmioApiDocBundle/issues/196

[hugomn]

+1 for this issue.

[b-durand]

@willdurand can you give a help? Thanks in advance.

[AlmogBaku]

@willdurand is there any solution for this issue?

[AlmogBaku]

I wrote the doc, the thing is I can't declare the annotation(use statement) in case it's not included. I would appreciate if you have any idea how to solve it in order to send a PR. (maybe an ugly class_exsits? edit: won't work, cause the annotation fail after looking for non-exsits class)

    /**
     * Authorize user
     * @ApiDoc(
     *  section="OAuth",
     *  requirements={
     *      { "name"="client_id", "dataType"="string", "description"="The client application's identifier"},
     *      { "name"="response_type", "dataType"="string", "requirement"="code|token", "description"="Response type"}
     *  },
     *  parameters={
     *      { "name"="redirect_uri", "dataType"="uri", "required"=false, "description"="The redirect URI registered by the client"},
     *      { "name"="scope", "dataType"="string", "required"=false, "description"="The possible scope of the request"},
     *      { "name"="state", "dataType"="string", "required"=false, "description"="Any client state that needs to be passed on to the client request URI"},
     *  }
     * )
     */
    public function authorizeAction(Request $request)

    /**
     * Get access token
     * @param  Request $request
     * @return type
     * @ApiDoc(
     *  section="OAuth",
     *  requirements={
     *      { "name"="client_id", "dataType"="string", "description"="The client application's identifier"},
     *      { "name"="client_secret", "dataType"="string", "description"="The client application's secret"},
     *      { "name"="grant_type", "dataType"="string", "requirement"="refresh_token|authorization_code|password|client_credentials|custom", "description"="Grant type"},
     *  },
     *  parameters={
     *      { "name"="username", "dataType"="string", "required"=false, "description"="User name (for `password` grant type)"},
     *      { "name"="password", "dataType"="string", "required"=false, "description"="User password (for `password` grant type)"},
     *      { "name"="refresh_token", "dataType"="string", "required"=false, "description"="The authorization code received by the authorization server(for `refresh_token` grant type`"},
     *      { "name"="authorization_code", "dataType"="string", "required"=false, "description"="The authorization code received by the authorization server (For `authorization_code` grant type)"},
     *      { "name"="scope", "dataType"="string", "required"=false, "description"="The scope of the authorization"},
     *      { "name"="redirect_uri", "dataType"="string", "required"=false, "description"="If the `redirect_uri` parameter was included in the authorization request, and their values MUST be identical"},
     *  }
     * )
     */
    public function tokenAction(Request $request)

[joshhornby]

Did this ever get fixed? Would love to know a solution

[AlmogBaku]

I created a new controller which extends from the original, and defined the routing to there.

[AlmogBaku]

My solution was to create two new controllers(and not define the routes from the configuration in the routing.yml:

<symfony_root>/src/Rimoto/ApiBundle/Controllers/OAuthAuthorizeController.php

<?php
/**
 * @author  Almog Baku
 *          almog.baku@gmail.com
 *          http://www.almogbaku.com/
 *
 * 14/04/15 22:53
 */

namespace Rimoto\ApiBundle\Controller;

use FOS\OAuthServerBundle\Controller\AuthorizeController;
use Nelmio\ApiDocBundle\Annotation\ApiDoc;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Component\HttpFoundation\Request;

/**
 * Class OAuthAuthorizeController
 * @package Rimoto\ApiBundle\Controller
 *
 * {@inheritdoc}
 * @Route("/oauth/v2")
 */
class OAuthAuthorizeController extends AuthorizeController {
    /**
     * Authorize user
     *
     * @Route("/auth", name="fos_oauth_server_authorize")
     * @Method({"GET","POST"})
     *
     * @ApiDoc(
     *  section="OAuth",
     *  requirements={
     *      { "name"="client_id", "dataType"="string", "description"="The client application's identifier"},
     *      { "name"="response_type", "dataType"="string", "requirement"="code|token", "description"="Response type"}
     *  },
     *  parameters={
     *      { "name"="redirect_uri", "dataType"="uri", "required"=false, "description"="The redirect URI registered by the client"},
     *      { "name"="scope", "dataType"="string", "required"=false, "description"="The scope of the authorization"},
     *      { "name"="state", "dataType"="string", "required"=false, "description"="Any client state that needs to be passed on to the client request URI"},
     *  }
     * )
     */
    public function authorizeAction(Request $request)
    {
        return parent::authorizeAction($request);
    }
}

<symfony_root>/src/Rimoto/ApiBundle/Controllers/OAuthTokenController.php:

<?php
/**
 * @author  Almog Baku
 *          almog.baku@gmail.com
 *          http://www.almogbaku.com/
 *
 * 14/04/15 22:56
 */

namespace Rimoto\ApiBundle\Controller;

use FOS\OAuthServerBundle\Controller\TokenController;
use FOS\OAuthServerBundle\Model\TokenInterface;
use Nelmio\ApiDocBundle\Annotation\ApiDoc;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Component\HttpFoundation\Request;

/**
 * Class OAuthTokenController
 * @package Rimoto\ApiBundle\Controller
 *
 * {@inheritdoc}
 * @Route("/oauth/v2", service="rimoto.api.oauth_server.controller.token")
 */
class OAuthTokenController extends TokenController {
    /**
     * Get access token
     * @param Request $request
     * @return TokenInterface
     *
     * @Route("/token", name="fos_oauth_server_token")
     * @Method({"GET","POST"})
     *
     * @ApiDoc(
     *  section="OAuth",
     *  output="FOS\OAuthServerBundle\Model\TokenInterface",
     *  requirements={
     *      { "name"="client_id", "dataType"="string", "description"="The client application's identifier"},
     *      { "name"="client_secret", "dataType"="string", "description"="The client application's secret"},
     *      { "name"="grant_type", "dataType"="string", "requirement"="refresh_token|authorization_code|password|client_credentials|custom", "description"="Grant type"},
     *  },
     *  parameters={
     *      { "name"="username", "dataType"="string", "required"=false, "description"="User name (for `password` grant type)"},
     *      { "name"="password", "dataType"="string", "required"=false, "description"="User password (for `password` grant type)"},
     *      { "name"="refresh_token", "dataType"="string", "required"=false, "description"="The authorization code received by the authorization server(for `refresh_token` grant type`"},
     *      { "name"="code", "dataType"="string", "required"=false, "description"="The authorization code received by the authorization server (For `authorization_code` grant type)"},
     *      { "name"="scope", "dataType"="string", "required"=false, "description"="If the `redirect_uri` parameter was included in the authorization request, and their values MUST be identical"},
     *      { "name"="redirect_uri", "dataType"="string", "required"=false, "description"="If the `redirect_uri` parameter was included in the authorization request, and their values MUST be identical"},
     *  }
     * )
     */
    public function tokenAction(Request $request)
    {
        return parent::tokenAction($request);
    }
}

<symfony_root>/app/config/routing.yml:

api:
    resource: "@ApiBundle/Controller/"
    type:     annotation
    prefix: /

[mappedinn]

nice idea :+1:

[GuilhemN]

Can't we create a custom nelmio extractor?

[quant61]

I tried @AlmogBaku 's solution apidoc works well but I get 500 error on POST /oauth/v2/token Catchable Fatal Error: Argument 1 passed to CompanyName\ClientBundle\Controller\OAuthInterfaceController::__construct() must be an instance of OAuth2\OAuth2, none given, called in project/vendor/symfony/symfony/src/Symfony/Component/HttpKernel/Controller/ControllerResolver.php on line 162 and defined

[quant61]

I found solution for my problem here so both method itself and apidoc for it work. Sorry if my posts are offtopic here.