Nelmioapidocbundle: Definition not loaded

[chucky2305]

I use following versions:
zircote/swagger-php in version 2.0.10
nelmio/api-doc-bundle in version v3.0.0-BETA4

/**
     * @Operation(
     *     tags={"DeliverySlip"},
     *     summary="Send information after deliveryItems are processed and deliverySlip was scanned",
     *     @SWG\Response(
     *         response="200",
     *         description="Returned when successful"
     *     ),
     *     @SWG\Response(
     *         response="400",
     *         description="Returned on a missing request parameter"
     *     ),
     *     @SWG\Response(
     *         response="500",
     *         description="Returned on any other error"
     *     ),
     *     @SWG\Parameter(
     *        name="slipIdentifier",
     *        description="identifier of delivery slip",
     *        type="string",
     *        format="string",
     *        in="path"
     *     ),
     *     @SWG\Parameter(
     *        name="JSON update body",
     *        in="body",
     *        description="json login request object",
     *        required=true,
     *        @SWG\Schema(ref="#/definitions/product")
     *     )
     * )
     *
     * @Put("/deliveryslip/update/{slipIdentifier}", requirements={"slipIdentifier" = "\w+"})
     *
     * @param string $slipIdentifier
     * @param Request $request
     * @return JsonResponse
     */
    public function updateDeliverySlipAction($slipIdentifier, Request $request)

This is the Model/Definition I want to use in my Controller-Action:

<?php

namespace Sendis\Presentation\RestBundle\Model;

use Swagger\Annotations as SWG;

/**
 * @SWG\Definition(
 *     definition="product",
 *     type="object",
 *     required={"name"}
 * )
 */
class Product
{
    /**
     * @SWG\Property(example="doggie")
     * @var string
     */
    public $name;
}

But when I go to my documentation page at /api/doc, I see this error:

Errors
Resolver error at paths./api/deliveryslip/update/{slipIdentifier}.put.parameters.1.schema.$ref
Could not resolve reference: #/definitions/product
The next thing I recognised: My product.php does not seem to be read by swagger at all. I can write whatever I want here. No errors, even if I misspell something. This brings me to the conclusion, that my product.php was not found by swagger at all.

I am helpful for every hint.

[chucky2305]

I found the Solution for my problem. I just needed to load the external Definition like so:

/**
     * @SWG\Put(
     *     path="/deliveryslip/update/{slipIdentifier}",
     *     tags={"DeliverySlip"},
     *     summary="Send information after deliveryItems are processed and deliverySlip was scanned",
     *     @SWG\Definition(
     *        definition="product",
     *        type="object",
     *        required={"name"}
     *     ),
     *     @SWG\Response(
     *         response="200",
     *         description="Returned when successful"
     *     ),
     *     @SWG\Response(
     *         response="400",
     *         description="Returned on a missing request parameter"
     *     ),
     *     @SWG\Response(
     *         response="500",
     *         description="Returned on any other error"
     *     ),
     *     @SWG\Parameter(
     *        name="slipIdentifier",
     *        description="identifier of delivery slip",
     *        type="string",
     *        format="string",
     *        in="path"
     *     ),
     *     @SWG\Parameter(
     *        name="JSON update body",
     *        in="body",
     *        description="json login request object",
     *        required=true,
     *        @SWG\Schema(
     *         type="array",
     *         @Model(type=Sendis\Presentation\RestBundle\Model\Product::class)
     *     )
     *     )
     * )
     *
     * @param string $slipIdentifier
     * @param Request $request
     * @return JsonResponse
     */
    public function updateDeliverySlipAction($slipIdentifier, Request $request)

[unglud]

Poor documentation made some things very hard, especially in this hacky metaprogramming with annotations. Thank you @chucky2305 for help!

[dbu]

if you see a way to improve the documentation, please contribute to this bundle by doing a pull request.

[GuilhemN]

We override swagger-php loader to only parse controllers methods so @Definition is not automatically detected. I guess this could be clearer in the docs indeed, a PR is welcome.

[GuilhemN]

Closing as it's fixed :)

[jayrajmfsi]

Very poor documentation. Can someone please provide a working Example of how to use defintions. Tried adding it in config.yml but with no success.

[GuilhemN]

@jayrajmfsi you don't need to use config to have definitions, you'd know it if you had read the docs: we have an annotation to define models/definitions https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html#use-models.

[jayrajmfsi]

But I dont want to create a new class everytime I create a model.I included definitions in config.
And did ->

 * @SWG\Response(
 *     response=200,
 *     description="Returns the details",
 *     @SWG\Schema(
 *       type="object", ref="#/definitions/Error"
 *     )

it worked fine.But can u tell how can SWG\Property work with definition and ref?
Like using :
* @SWG\Schema(
* @SWG\Property(type="integer",property="id", description="id"),
* @SWG\Property(type="object", property="ref")
* )
* )
I dont know what to write in the "ref" portion?
I want similar to this as given in the swagger api specs:
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
}

[GuilhemN]

@SWG\Property works the same way as @SWG\Schema, just do @SWG\Property(property="adress", ref="#/definitions/Address")

[jayrajmfsi]

It worked. Thanks a lot.

[jayrajmfsi]

Hi other issues resolved while continuing. Like using allOf and how to add enum.

[GuilhemN]

You can have a look at zircote/swagger-php docs (https://github.com/zircote/swagger-php/blob/master/docs/Getting-started.md) to understand better how our annotations work.

[jayrajmfsi]

Thanks for the link. Moreover can you tell me how to use allOf. Thank you

[GuilhemN]

Well allof can be used like this:

/**
 * @SWG\Schema(allOf={@SWG\Schema(...), @SWG\Schema(...)})
 */

and enum:

/**
 * @SWG\Schema(enum={"foo", "bar"})
 */

You can take a look at php docs to understand how annotations work: https://github.com/zircote/swagger-php/blob/master/src/Annotations/Schema.php#L199.