Nelmioapidocbundle: Where do global definitions go?

[pdugas]

I have a number of APIs that accept the same parameters and would like to define them in one place the refer to them elsewhere. I'm not sure where to put them. My controllers are all in src/AppBundle/Api/*Controller.php. I've tried adding a spec.php file in that directory like so:

<?php
use Swagger\Annotations as SWG;
/**
 * @SWG\Parameter(
 *     parameter="eg_foo",
 *     name="foo",
 *     ...
 * )
 */

Then tried to reference this in the @SWG\Operation annotation in a controller like so:

    /**
     * @API\Operation(
     *     @SWG\Parameter(ref="#/parameters/eg_foo"),
     */

I'm getting an error about in and name being required for properties in the constructor for the Properties class.

[pdugas]

I've also tried adding the definition to app/confg/config.yml like so:

nelmio_api_doc:
    documentation:
        parameters:
            eg_foo:
                name: length
                type: integer
                format: int64
                in: query
                required: false

Still getting the same error.

[pdugas]

Hmmm.... When I added those lines to config.yml, I get an extra paths entry in the generated JSON swagger-data.

[GuilhemN]

I've tried adding a spec.php file in that directory

Only annotations in controllers are parsed.

I'm getting an error about in and name being required for properties in the constructor for the Properties class.

I can't investigate right now but at first sight it looks like an issue in zircote/swagger-php, can you open an issue there ?

[pdugas]

My gut feeling is that the parameter definition isn't being loaded anywhere so the @SWG\Parameter(ref="#/parameters/eg_foo") essentially becomes an empty Parameter with the required in and name setting omitted. Hence the error message.

I tried using the spec.php file after seeing the using-refs example. I guess that approach is not supported here.

I tried adding the @SWG\Parameter(parameter=..) annotation in the /** ... */ comment just before one of my controller class definitions and am still getting the same error. Feels like something's fundamentally wrong with my approach.

[GuilhemN]

I'm closing as https://github.com/GuilhemN/swagger/pull/2 and https://github.com/nelmio/NelmioApiDocBundle/pull/1042 are merged. Feel free to reopen if this is still happening.

[nbucic]

I've encountered the same problem. When I define global parameter

documentation:
    info:
        title: Awesome APP
        description: Awesome APP documentation
        version: 1.0.0
    parameters:
        dateFrom:
            in: query
            name: dateFrom
            description: "Timestamp, used for filtering data. Inclusive"
            type: integer
        dateTo:
            in: query
            name: dateTo
            description: "Timestamp, used for filtering data. Inclusive"
            type: integer

and try to use it in controller with following SWG annotation:

/**
 * @SWG\Parameter(
 *     ref="/parameters/dateFrom"
 * )
 */

I'm getting this error:
User Notice: $ref "#/parameters/dateFrom" not found for @SWG\Parameter() in \AnalyticsController->getAnalyticsAction()

[AshleyDawson]

+1

I'm getting this issue as well. I'm trying to define global parameters and then use "ref" to link them and I'm getting the exact same issue as @nbucic. Please help as this is infuriating!

[nbucic]

Problem is at https://github.com/nelmio/NelmioApiDocBundle/blob/2b15539cc3be700e0d689cfededc68194b1aa1f9/DependencyInjection/NelmioApiDocExtension.php#L107

The part from the config.yml is taken as is, without validation and without creating back-references to them

[AshleyDawson]

If you add the following try block to: Nelmio\ApiDocBundle\ApiDocGenerator (Line ~60):

        foreach ($this->describers as $describer) {
            if ($describer instanceof ModelRegistryAwareInterface) {
                $describer->setModelRegistry($modelRegistry);
            }

            try {
                $describer->describe($this->swagger);
            } catch (\Exception $e) {
                dump($e, $describer, $this->swagger);
            }
        }

... in dump(), $this->swagger contains a set of parameters configured globally, however when you dive into Swagger\Analysis::validate() (Line ~328) you'll see that the instance of $this->swagger used there to validate is a a different instance (without the parameters defined).

So, it looks like that the globally configured parameters are successfully being passed in and then lost during validation... or it's a completely different instance of Swagger...

[AshleyDawson]

Still can't figure this one out - it's causing a lot of pain. Please could the author take a look?

[devrck]

@AshleyDawson please check https://github.com/nelmio/NelmioApiDocBundle/issues/1085

[devrck]

Simple answer is to downgrade zircote/swagger-php to 2.0.10

[GuilhemN]

The issue is we don't provide the global config to zircote/swagger-php, I guess we should just provide global parameters and it should be enough.

[fcojavierdomenech]

In my case worked as soon as I created the inand name attribute:

        parameters:
            tripStatus:
                in: ''
                name: 'tripStatus'
                type: int
                description: 'Status of the trip, there are several possible values in regard of the current state of the trip:<ul>
                <li><0 - None></li>
                <li><1 - Requested></li>
                </ul>
                '
                enum:
                    - 0
                    - 1
                    - 2
                    - 3
                    - 4