Nelmioapidocbundle: Support for collections to output

Created on 21 Dec 2013 · 25Comments · Source: nelmio/NelmioApiDocBundle

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?

enhancement

Source

Drachenkaetzchen

Most helpful comment

How is this requirement different from what was already merged here:
https://github.com/nelmio/NelmioApiDocBundle/pull/469

duncangrist on 7 Apr 2016

👍3

All 25 comments

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"
)

maphe on 23 Dec 2013

chrisapl on 7 Jan 2014

+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

mtotheikle on 8 Jan 2014

Anyone to work on this feature?

willdurand on 8 Jan 2014

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);
    }
}