在 Swagger / Zircote / Nelmio-api-doc 中使用外部定义

Posted 2023-02-16

【中文标题】在 Swagger / Zircote / Nelmio-api-doc 中使用外部定义

【英文标题】：using external Definitions in Swagger / Zircote / Nelmio-api-doc

【发布时间】：2018-03-17 00:02:25

【问题描述】：

我使用以下版本：

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)

这是我想在 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;

但是当我转到 /api/doc 的文档页面时，我看到了这个错误：

Errors
Resolver error at paths./api/deliveryslip/update/slipIdentifier.put.parameters.1.schema.$ref
Could not resolve reference: #/definitions/product

接下来我认识到： swagger 似乎根本没有阅读我的 product.php。我可以在这里写任何我想写的东西。没有错误，即使我拼错了什么。这让我得出结论，swagger 根本找不到我的 product.php。

我对每一个提示都有帮助。

亲切的问候， 最大

【参考方案1】：

我找到了解决这个问题的方法。我需要像这样加载具有完整命名空间的外部定义：

/**
     * @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)