Support for collections to output

Drachenkaetzchen commented 10 years ago

My API returns a list of objects. The annotation is as follows:

@ApiDoc(
description="Retrieves all SI Prefixes in the database",
output="PartKeepr\SiPrefixBundle\Entity\SiPrefix"
 )

This works fine, however, it doesn't indicate that PartKeepr\SiPrefixBundle\Entity\SiPrefix is an array. I could, of course, add a collection, but simply putting up a separate collection with proper type hints leads to lots of duplication. I would have expected to specify the output as JMSType specification, e.g. something like this:

@ApiDoc(
description="Retrieves all SI Prefixes in the database",
output="ArrayCollection<PartKeepr\SiPrefixBundle\Entity\SiPrefix>"
 )

However, this doesn't work. Is there any other way to specify that a collection is returned?

maphe commented 10 years ago

I add a complementary request : Suposing that we can now specify that the api returns a collection/array, how can we manage abstract entities using DiscriminatorMap ?

Example :

I have an abstract entity/document Vehicle extended by 2 classes Car and Truck. I want my api to return a list of vehicles, which can be one or another, how to specify it?

Supposition :

@ApiDoc( output="ArrayCollection<Namespace\To\Entity\Car|Namespace\To\Entity\Truck>" )

chrisapl commented 10 years ago

+1

mtotheikle commented 10 years ago

+1 In my case I have an abstract pager object that has information for pagination and then a results array. I need a way to document the results array for a particular endpoint will be a specific type

willdurand commented 10 years ago

Anyone to work on this feature?

lgoral commented 10 years ago

Hi My question is if that is correct, and create PR?

In my project i created service

    mybundle.api_doc.extractor.custom_parser:
        class: My\Bundle\Parser\ApiDocOutputArray
        arguments: ['@nelmio_api_doc.parser.jms_metadata_parser']
        tags:
            - { name: nelmio_api_doc.extractor.parser, priority: 2 }

and code which read output parameter

output="ArrayCollection<Namespace\To\Entity\Car>"

use Nelmio\ApiDocBundle\Parser\JmsMetadataParser;
use Nelmio\ApiDocBundle\Parser\ParserInterface;

class ApiDocOutputArray implements ParserInterface
{

    /**
     * @var JmsMetadataParser
     */
    private $jmsMetadataParser;

    public function __construct(JmsMetadataParser $jmsMetadataParser)
    {
        $this->jmsMetadataParser = $jmsMetadataParser;
    }

    /**
     * {@inheritdoc}
     */
    public function supports(array $item)
    {
        list($className, $type) = $this->getClassType($item);

        if (empty($className) || empty($type)) {
            return false;
        }

        $item['class'] = $className;

        return $this->jmsMetadataParser->supports($item);
    }

    /**
     * {@inheritdoc}
     */
    public function parse(array $item)
    {
        list($className, $type) = $this->getClassType($item);

        if (empty($className) || empty($type)) {
            return false;
        }

        $exp = explode("\\", $className);

        $item['class'] = $className;

        $returnData = array('dataType' => $type,
            'required' => true,
            'description' => sprintf("%s of objects (%s)", $type, end($exp)),
            'readonly' => false,
            'children' => $this->jmsMetadataParser->parse($item)
        );

        return array('[]' => $returnData);
    }

    /**
     * @param array $item
     *
     * @return array
     */
    private function getClassType(array $item)
    {
        $className = $type = '';
        if (preg_match('/(.+)\<(.+)\>/', $item['class'], $match)) {
            $className = $match[2];
            $type = $match[1];
        }

        return array($className, $type);
    }
}