nelmio / nelmioapidocbundle Goto Github PK

Hi

I was trying to use a "stable" release and I used in my composer.json

    "nelmio/api-doc-bundle":"2.*@stable",

Which downloads version 2.0.0 of the bundle

But when trying to generate my api documentation I get the following error:

Call to undefined method Symfony\Component\Routing\CompiledRoute::getRequirements() in /datos/socialpoint/sp-platform-dragoncity/vendor/nelmio/api-doc-bundle/Nelmio/ApiDocBundle/Extractor/ApiDocExtractor.php on line 234

This is a line where

    foreach ($route->compile()->getRequirements() as $name => $value) {

And CompiledRoute.php from SF2.1 does not have getRequirements method (Route.php, does have it, however). I am using Symfony 2.1.2.

Using composer.json pointing to dev-master works but we would like to have tagged versions

Can you confirm this issue and if confirmed get this tag to be fixed?

Best regards

The Parser\FormTypeParser class contains a map FormType => data type, but it doesn't take care of custom FormType (datepicker, etc.).

We need a way to add new entries to this map through configuration.

Catchable Fatal Error: Argument 2 passed to Nelmio\ApiDocBundle\Parser\JmsMetadataParser::getDescription() must be an instance of JMS\SerializerBundle\Metadata\PropertyMetadata, instance of JMS\Serializer\Metadata\PropertyMetadata given, called in C:\Users\K\Documents\payrobin\webapp\vendor\nelmio\api-doc-bundle\Nelmio\ApiDocBundle\Parser\JmsMetadataParser.php on line 85 and defined in C:\Users\K\Documents\payrobin\webapp\vendor\nelmio\api-doc-bundle\Nelmio\ApiDocBundle\Parser\JmsMetadataParser.php line 172

If there is an unsupported field type (like choice) in an AbstractType subclass object, the field is not included in the generated documentation.

It would be better, if the field was shown without any type specified or with some fallback type (like string).

There is in issue with the topsort in parsing JMS metadata tags that causes infinite recursion.

Example that the topsort works for:

@Type("\Acme\DemoBundle\Entity\Parent")
  @Type("\Acme\DemoBundle\Entity\Child")

Example where it fails:

@Type("\Acme\DemoBundle\Entity\Parent")
  @Type("\Acme\DemoBundle\Entity\Unrelated")
  @Type("\Acme\DemoBundle\Entity\Child")
    @Type("\Acme\DemoBundle\Entity\Parent")

What happens is that ->parse is called on the Parent, adding it to the 'parsedClasses', then Unrelated is found and parsed, however because it has no subtypes it clears the global parsedClasses, so when it then continues on with Child, it finds that it has a Parent, but has already forgotten that it has parsed this before.

When using the FOSRestBundle custom actions, they all end up in the others part of the doc as they don't have the same url than the main resource. Thus, the list and the individual item are different resources and are separated. It would be good to have sections to group actions together. This way, the other part would be splitted into each section, staying with the other actions applied on the same objects.
And the bundle would define a default section containing all methods which don't have a section defined (which could be done at the class level once #3 is implemented)

We shoud can choose to show or hide sandbox.

FOSRestBundle uses PATCH for the additional methods now. But the HTML formatter does not display routes nicely when using the PATCH method (not consistent with POST, PUT, GET or DELETE)

Hi all,

I don't know if this Exception is a real issue but in all cases...

I upgraded Nelmio to the latest version and I had to move request_listener.enable option to false

request_listener:
        enabled: false

if set to true, this errors is returned:

<abbr title="Symfony\Component\DependencyInjection\Exception\ServiceCircularReferenceException">ServiceCircularReferenceException</abbr>: Circular reference detected for service "templating", path: "nelmio_api_doc.event_listener.request -> nelmio_api_doc.formatter.html_formatter -> templating -> twig -> twig.extension.httpkernel -> http_content_renderer -> http_content_renderer.strategy.hinclude".

Could someone help me on this please?

I've attempted to find what is causing this, but get stuck once it hits the doctrine annotation reader.

Nothing is returned from this call when it hits a auto generated FOSRestBundle generated route.

if ($annotation = $this->reader->getMethodAnnotation($method, self::ANNOTATION_CLASS)) {}

see FriendsOfSymfony/FOSRestBundle#185 and
https://github.com/FriendsOfSymfony/FOSRestBundle/blob/master/Resources/doc/3-listener-support.md#query-fetcher-listener

Simple FormType works great, but when I add DataTransformers, docs for input becomes empty.

Right now the login_check is not a controller at the application level so it's impossible to tag it with an annotation, I'm not sure if there is a way to achieve this simply.

I'd like to add some parameter to template coming from a custom parser.
Is there any other solution than fork the repo and make my own method.html.twig ?

thanks

APIs are not always fully public and you might want to generate a doc for public users and another documentation for internal use. This feature needs a bit of discussion on how to implement it, though.

Hi guys, I was trying to submit a form using the sandbox, this is the method annotations

/**
 * Create a new team
 *
 * @Route(".{_format}", name="api_team_create")
 * @Method("POST")
 * @ApiDoc(
 *  description="Creates a new team",
 *  statusCodes={
 *   200="Player informations are returned",
 *   403="The user isn't authorized"
 *  },
 *  input="Acme\TeamBundle\Form\TeamType",
 *  return="Acme\TeamBundle\Entity\Team"
 * )
 *
 * @return Renders the team just created
 */

the problem is that TeamType class has a name:

public function getName()
{
    return 'team';
}

so the parameters should be built using:

team[parameter]

and not just

parameter

Shouldn't this be the correct behavior or am I missing something?

This makes sense when developing and being offline.

Doing this :
/**
* @apidoc(
* description="Get all users",
* output="AppMyTaxi\UserBundle\Entity\User")
* @rest\View
*/
public function getUsersAction() {
...
}
Get us this error :
"
Catchable Fatal Error: Argument 2 passed to
Nelmio\ApiDocBundle\Parser\JmsMetadataParser::getDescription() must be
an instance of JMS\SerializerBundle\Metadata\PropertyMetadata, instance
of JMS\Serializer\Metadata\PropertyMetadata given, called in .../vendor/nelmio/api-doc-bundle/Nelmio/ApiDocBundle/Parser/JmsMetadataParser.php
on line 85 and defined in .../vendor/nelmio/api-doc-bundle/Nelmio/ApiDocBundle/Parser/JmsMetadataParser.php
line 172
"
I have tried with a lot of different controller, and only one is working.
I tried to find a pattern but nothing so far.

I'm working on adding a new property to the @apidoc annotation. This will let you specify 'return' in @apidoc to have have api method response structures automatically documented. This return could be specified in a couple of ways:

@ApiDoc(
    return="array('user'=>MyBundle\User\UserClass)"
)

@ApiDoc(
    return="MyBundle\User\UserClass"
)

//same as above, but implies something different, see explanation below

@ApiDoc(
    return="MyBundle\Form\UserType"
)

This will import data for the "return" property in one of several ways:

• Case 1 above - specifying an array of properties mapped to domain objects, each object can be parsed in the methods described below:
• Case 2 above - Specify a class, which may be annotated with JMS Serializer annotations, if it's not annotated, reflection can get public properties, and or properties with corresponding public getter/setter methods
• Case 3 above - Specify a form type, which the bundle already knows how to parse

Implementing

There will most likely need to be multiple ways of parsing data object metadata, as mentioned in this issue #12

This would also take care of issue #20

The suggestions there for a ParserInterface could be implemented to allow parsing JMS annotations, and potentially others.

After that, the "return" property can be added as a new property handled by the @apidoc annotation.

Trying to setup a simple example with NelmioApiDocBundle. I'm guessing this is because the bundle is following Symfony2 master. Is there a way to add 2.0 support or can you point me to instructions to following 2.1 master? Thanks

Fatal error: Call to undefined method Symfony\Component\Routing\Route::addOptions() in /src/projecti/vendor/bundles/Nelmio/ApiDocBundle/Extractor/ApiDocExtractor.php on line 203

Call Stack:
    0.0003     327544   1. {main}() /src/projectweb/app_dev.php:0
    0.0066     817800   2. Symfony\Component\HttpKernel\Kernel->handle() /src/project/web/app_dev.php:37
    0.0212    1113160   3. Symfony\Bundle\FrameworkBundle\HttpKernel->handle() /src/project/app/bootstrap.php.cache:547
    0.0213    1113796   4. Symfony\Component\HttpKernel\HttpKernel->handle() /src/project/app/cache/dev/classes.php:4879
    0.0213    1113796   5. Symfony\Component\HttpKernel\HttpKernel->handleRaw() /src/project/app/cache/dev/classes.php:3875
    0.0799    1669508   6. call_user_func_array() /src/project/app/cache/dev/classes.php:3905
    0.0799    1669640   7. Nelmio\ApiDocBundle\Controller\ApiDocController->indexAction() /src/project/app/cache/dev/classes.php:3905
    0.0800    1669640   8. Nelmio\ApiDocBundle\Extractor\ApiDocExtractor->all() /src/project/vendor/bundles/Nelmio/ApiDocBundle/Controller/ApiDocController.php:21
    0.2217    2097108   9. Nelmio\ApiDocBundle\Extractor\ApiDocExtractor->getData() /src/project/vendor/bundles/Nelmio/ApiDocBundle/Extractor/ApiDocExtractor.php:67


Variables in local scope (#9):
  $annotation = class Nelmio\ApiDocBundle\Annotation\ApiDoc { private $filters = array ('a-filter' => array ('dataType' => 'integer'), 'another-filter' => array ('dataType' => 'string', 'pattern' => '(foo|bar) ASC|DESC')); private $formType = NULL; private $description = 'This is a description of your API method'; private $isResource = TRUE }
  $comment = *uninitialized*
  $comments = *uninitialized*
  $docblock = '@ApiDoc(\n resource=true,\n description=\\"This is a description of your API method\\",\n filters={\n {\\"name\\"=\\"a-filter\\", \\"dataType\\"=\\"integer\\"},\n {\\"name\\"=\\"another-filter\\", \\"dataType\\"=\\"string\\", \\"pattern\\"=\\"(foo|bar) ASC|DESC\\"}\n }\n )\n \n @return \\FOS\\RestBundle\\View\\View\n /'
  $line = ' /'
  $matches = array ()
  $method = class ReflectionMethod { public $name = 'getProfilesAction'; public $class = 'Project\\Bundle\\ApiBundle\\Controller\\ProfilesController' }
  $paramDocs = array ()
  $route = class Symfony\Component\Routing\Route { private $pattern = '/profiles.{_format}'; private $defaults = array ('_controller' => 'Project\\Bundle\\ApiBundle\\Controller\\ProfilesController::getProfilesAction', '_format' => 'json'); private $requirements = array ('_method' => 'GET'); private $options = array ('compiler_class' => 'Symfony\\Component\\Routing\\RouteCompiler'); private $compiled = NULL }

it would be good to extract information about the url pattern placeholders from the route definition and if available use the @param docblock

Hi, this is a great resource, but I'm not sure of the best way to define the properties of the underlying Class in the documentation. I'd like a section "Properties" that draws from the Exposed properties, i.e.

properties="Acme/DemoBundle/Entity/Comment",

Is there a way to do this with the Nelmio Bundle? Thanks!

It could be nice to display information at the beginning of the document like conventions, dev URLs, crendentials, whatever... It should be an option btw.

When using JMSSerializerBundle, it would be great to be able to see the format of the response in the doc (taken from the serializer metadata)

Hi

I am trying to sandbox a url which can be accessed indistinctly by GET or POST.

With SF2 I've got the option of not specify anything or specify GET|POST but in those cases NelmioApiDocBundle sends request with a Method "ANY" or "GET|POST" which causes HttpFoundation component to remove form data or even give a 405.

How can we deal with this in the sandbox mode?

I have a method with the following annotation:

/**
 * Create a new product.
 * A product itself is not tied to a particular language - hence no language information is required.
 *
 * @Route("/products")
 * @Method("POST")
 * @ApiDoc(
 *   description="Create new product.",
 *   input="Frisbee\ProductBundle\Form\Type\ProductApiCreateType"
 * )
 */

The ProductApiCreateType form looks like this:

<?php
namespace Frisbee\ProductBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Collection;

class ProductApiCreateType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('name');
        $builder->add('categories', 'entity', array(
            'class' => 'FrisbeeProductBundle:ProductCategory',
            'property' => 'name',
        ));
    }

    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $collectionConstraint = new Collection(array(
            'name' => new NotBlank(),
            'categories' => new NotBlank()
        ));

        $resolver->setDefaults(array(
            'constraints' => $collectionConstraint
        ));
    }

    public function getName()
    {
        return 'product';
    }
}

Whenever the documentation is generated, the following exception is thrown:

The required option "class" is missing.
in /[...]/vendor/symfony/symfony/src/Symfony/Component/OptionsResolver/OptionsResolver.php at line 278

I haven't been able to work around this - any thoughts?

Sandbox should use Accept and Content-Type headers instead of adding _format parameter into the request. Or it should be configurable.

Otherwise form validation might fail: This form should not contain extra fields.

Right now, the various parsers set dataType however they want, which is fine for text documentation. However, in order to implement formatters that build formats consumable by other programs, for example WSDL, Swagger, or other, this property needs to have standard values that the formatters can act on accordingly.

This would affect implementation of #99 and #48.

On each API method, it should be possible to try it thanks to a sandbox. This is a common feature in other API doc generators. This sandbox must use its own data.

As a developer using this API, in order to know how things work, I want to:

• be able to execute a method;
• to see the request;
• to see the response;
• to fill in my own parameters if needed.

Hi,
I am using Symfony 2.0.12 and I got this error after installing the bundle :

Declaration of Nelmio\ApiDocBundle\Form\Extension\DescriptionFieldTypeExtension::getDefaultOptions() must be compatible with that of Symfony\Component\Form\FormTypeExtensionInterface::getDefaultOptions()

I already have a similar problem so I think it is a compatibility problem with my version of Symfony. Is the bundle compatible with 2.0.x version of symphony or only the master ?

Or that has no relation...

Thanks

There should be some way of documenting error responses for API routes. This could be done semi-automatically by scanning for @throws docblock params, but that likely won't cover all cases. This isn't required, but would be very useful for #48.

The Formatter/AbstractFormatter.php use the required field attribute. For hidden fields this is false (HTML5 hidden fields don't have and required attr). So it would be better to also check the validation rules.

Hello,

it would be great that the ApiDoc detect the "Secure" annotation, or add an option to indicate that the api controller need an authentication and show it in the doc (with a padlock for exemple).

Thx !

Suppose you use an entity for your input class, it would be nice if the "required" flag on the documentation would read from the @Orm annotation. For example, I have a property like the following:

    /**
     * @var string $recordType
     *
     * @ORM\Column(name="record_type", type="integer", nullable=false)
     * @JMS\Type("integer");
     * @JMS\SerializedName("record_type");
     * @Assert\NotBlank()
     * @Assert\Choice(choices = {"distributions", "diversifications", "dividends", "oia_dividends", "restricted_stock"}, message = "Choose a valid record type")
     */
    private $recordType;

It would be really nice if the "nullable" attribute was read. I could also see the "Assert\NotBlank()" doing this. If we had a way to utilize the "Assert\Choice" list that would be especially nice.

I didn't see a way to set the description for input parameters using an entity with JMS.

• optional filtering by URL prefix

This bundle could support Swagger-compliant JSON. This would have several benefits:

• Swagger-ui would work on any implementing server.
• Swagger-codegen could be used to generate code clients for any api, making it very easy for other developers to use your api

In order to do this, we need to be able to also document input/output models for api methods. The bundle already supports documenting input models via the formType property, and there is a proposal to allow documenting return types in #47.

If these issues are taken care of, supporting Swagger JSON could be done by implementing a new SwaggerFormatter, and adding a new controller action in ApiDocController, which would return the necessary resources.json spec.

It seems that structure returned in JMS\SerializerBundle\Metadata\ClassMetadata for property type has changed from string to array

I have following property:

    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     *
     * @Type("integer")
     */
    protected $customerId;

JmsMetadataParser::parse calls getMetadataForClass and gets following output:

  public 'propertyMetadata' => 
    array (size=18)
      'customerId' => 
        object(JMS\SerializerBundle\Metadata\PropertyMetadata)[433]
          public 'type' => 
            array (size=2)
              'name' => string 'integer' (length=7)
              'params' => 
                 array (size=0)
                 empty

So "type" is now an array with two keys: name and params and:

$dataType = $this->processDataType($item->type);

needs to be changed to:

$dataType = $this->processDataType($item->type['name']);

Hi,

I'm getting fatal error with latest bundle version and framework version 2.1.3:

Fatal error: Call to a member function defaultValue() on a non-object in /var/www/testapp/vendor/bundles/Nelmio/ApiDocBundle/DependencyInjection/Configuration.php on line 47

https://github.com/nelmio/NelmioApiDocBundle/blob/master/DependencyInjection/Configuration.php#L42-L54

When I comment out that part and provide some values in NelmioApiDocExtension.php everything works as expected.

Is this bug or i'm missing some configuration values?

Thanks!

Say you have a form with the name "user", and a parameter called "username".

At the moment there seems to be inconsistency between the documentation generated and the content expected.

The documentation generated says that I should POST a parameter called "username", but the form expects "user[username]" to be posted.

So - the documentation should either say that the parameter should be named "user[username]", or (perhaps better), the form should look in the "username" field instead of the "user[username]" field.

Does it make sense? :-)

I'm using FOSRestBundle with JMSSerializerBundle for my API. The input isn't specified with a Form but with a Class that is annotated with JMSSerializer annotations.

Would it be possible to support this too?

When registering form types through the form.type DIC tag, it would be great to be able to specify the form type by its name instead of using the class name.

When the application is not at the root of the domain, the path used by the sandbox is wrong. And as the path is a DIC parameter, it is impossible to provide a setup using the current request to determine the base path as it would require knowing the base path when building the container. So the default value is simply broken.

"pattern"="1000/asd/2012" => 1000/asd/2012

It should probably be possible to:

• guess the root name from the form type (when using FormFactory#create() this is used as root name)
• configure the form root name in the annotation