Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Add possibility to specifiy HTTP verb in annotations #131

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
4 participants

Add a "method" parameter to the ApiDoc annotation, allowing
to set the HTTP verb of the method.
Useful when you can't use Routing method requirement.
Uses the specified method in the annotation. If none, uses the
requirements of the route. If none, fallback to 'ANY'
Example:

<?php
    /*
     * My actions full description
     *
     * @ApiDoc(
     *   method = "POST",
     *   description = "This is a description of your API method",
     *   statusCodes = {
     *      201 = "Returned when successful",
     *      405 = "Returned when HTTP verb isn't supported"
     * })
     *
     * @Route(
     *     name     = "my_route",
     *     pattern  = "/my/url",
     *     defaults = { "_format" = "json" }
     * )
     */
    public function myAction()

Remark

No tests yet, as I can't install the vendors.

>php composer.phar update --dev --prefer-dist

Loading composer repositories with package information
Updating dependencies
Nothing to install or update
Loading composer repositories with package information
Updating dev dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for friendsofsymfony/rest-bundle dev-master -> satisfiable by friendsofsymfony/rest-bundle dev-master.
    - jms/serializer-bundle 0.9.0 conflicts with friendsofsymfony/rest-bundle dev-master.
    - Installation request for jms/serializer-bundle 0.9.* -> satisfiable by jms/serializer-bundle 0.9.0.
@clemherreman clemherreman Add possibility to specifiy HTTP verb in annotations
Add a "method" parameter to the ApiDoc annotation, allowing
to set the HTTP verb of the method.
Useful when you can't use Routing method requirement.
Uses the specified method in the annotation. If none, uses the
requirements of the route. If none, fallback to 'ANY'
9e3d7a0

Also I haven't updated the README yet, more to come soon :)

Collaborator

willdurand commented Jan 24, 2013

Wait, what? I wonder why you couldn't use the Routing configuration?

If I use the routing configuration, I've not enough control on what is returned by Symfony. The API I'm designing must always return an http request with Content-Type: application/json, and a body with JSON (excepted HEAD requests).

If I use this :

<?php // Controller.php
    /*
     * @Route(
     *     name     = "my_url",
     *     pattern  = "/my/url",
     *     defaults = { "_format" = "json" }
     * )
     *
     * @Method({"POST"})
     */
    public function generateAction()

Symfony automatically returns a Content-Type: text/html, along with a body like this one, when querying /my/url via something else than POST

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title>An Error Occurred: Method Not Allowed</title>
    </head>
    <body>
        <h1>Oops! An Error Occurred</h1>
        <h2>The server returned a "405 Method Not Allowed".</h2>

See symfony/symfony#3215. As my application isn't full JSON, I can't use any of the suggested solutions there, and I've already written a lot of routing using annotation, so fallbacking on YAML or XML routing isn't really something I'd like to do.

The only remaining option is to have a similar code called in API controller method, unless I missed something.

<?php // Controller.php
    /*
     * @Route(
     *     name     = "my_url",
     *     pattern  = "/my/url",
     *     defaults = { "_format" = "json" }
     * )
     */
    public function generateAction() 
    {
        if ($this->getRequest()->getMethod() !== 'POST') {
            throw new MethodNotAllowedHttpException(array('POST'));
        }

I factorized this in a method, so it's not really a problem, but the generated documentation show a ANY method for methods that returns a 405 when not called via POST or GET or whatever.

Also, any ideas on why I can't install the bundles depencies ? That really prevents me from running the existing tests, and addind some more for the PR.

Ping my switzerland fellow developers. Does that sounds good to you, before I add tests and polish this a little?

Also, any ideas why I can't manage to run the test suite, a.k.a. the composer wtf?

Any news ?

Owner

Seldaek commented Feb 12, 2013

This is kinda hackish, I mean if your api can't handle anything else than POST you really should specify it in the routing. But yeah I see your problem, and I guess it doesn't really hurt to have the option to specify it by hand, even though it should be discouraged.

A few comments:

  • Please add tests
  • Fix the indenting
  • Allow string values as well as arrays for the method

As for the composer issue, I don't think you can use it with FOSRestBundle dev-master anymore until we fix the compatibility with the latest JMSSerializer.

Contributor

drgomesp commented Feb 14, 2013

@clemherreman

Have you managed to fix the tests yet? I'm having the same issue with my PR, #138.

Collaborator

willdurand commented Mar 16, 2013

Hi,

Somehow all answers since I asked for news went straight to my spam folder, hence the lack of news from me.
@Seldaek I'll amend the PR to anwser your comments, I'll get back to you if I still have troubles running the test suite :)

Collaborator

willdurand commented Apr 17, 2013

@willdurand willdurand closed this Jun 18, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment