Symfony、nelmio/api-doc-bundle 和 @SWG\SecurityScheme

Question

我正在尝试使用 nelmio/api-doc-bundle 记录我的 Symfony 3.4 应用程序 API，但未能创建安全方案。

使用以下配置生成文档本身可以按预期工作：

nelmio_api_doc:
    documentation:
        info:
            description: FooBar API
            title: FooBar
            version: 1.0.0
    routes:
        path_patterns:
            - ^/api/

以及以下注释：

/**
 * @SWG\Get(
 *     security={
 *         {"ApiKeyAuth":{}}
 *     },
 *     @SWG\Response(
 *         response=200,
 *         description="Returns all [Foo]",
 *         @SWG\Schema(
 *             type="array",
 *             @Model(type=App\Entity\Foo::class)
 *         )
 *     ),
 *     @SWG\Response(
 *         response=404,
 *         description="Returns an error when no [Foo] were found"
 *     )
 * )
 */
public function cgetAction(): Response
{
    // ...
}

所以我得到了一个像这样的正确 JSON 文件：

{
    "swagger" : "2.0",
    "info" : {
        "title" : "FooBar",
        "description" : "FooBar API",
        "version" : "1.0.0"
    },
    "paths" : {
        "\/api\/foo" : {
            "get" : {
                "responses" : {
                    "200" : {
                        "description" : "Returns all [Foo]",
                        "schema" : {
                            "items" : {
                                "$ref" : "#\/definitions\/Foo"
                            },
                            "type" : "array"
                        }
                    },
                    "404" : {
                        "description" : "Returns an error when no [Foo] were found"
                    }
                },
                "security" : [
                    {
                        "ApiKeyAuth" : [ ]
                    }
                ]
            }
        }
    },
    "definitions" : {
        "Foo" : {
            "properties" : {
                "id" : {
                    "type" : "integer"
                }
            },
            "type" : "object"
        }
    }
}

现在的问题是我需要定义ApiKeyAuthanywhere。根据我找到的示例...

https://github.com/zircote/swagger-php/blob/master/Examples/petstore.swagger.io/controllers/StoreController.php

https://github.com/zircote/swagger-php/blob/master/Examples/petstore.swagger.io/security.php

https://swagger.io/docs/specification/2-0/authentication/api-keys/

...可能如下所示：

/**
 * @SWG\SecurityScheme(
 *     name="X-API-KEY",
 *     type="apiKey",
 *     in="header",
 *     securityDefinition="ApiKeyAuth"
 * )
 */

但无论我将它放在控制器中的哪个位置，它都无法识别。

那么合适的地方在哪里呢？

我可以配置 api-doc-bundle 以识别具有全局定义的文件吗？

我需要在配置中创建定义而不是作为注释吗？

真的有用吗？

Answer 1

为了让它工作 ...

需要做一个小改动

/**
 * @SWG\Get(
 *     security={
 *         {"ApiKeyAuth":{}}
 *     },
 *     ...
 *     @SWG\Swagger(
 *         schemes={"https"},
 *         @SWG\SecurityScheme(
 *             name="X-API-KEY",
 *             type="apiKey",
 *             in="header",
 *             securityDefinition="ApiKeyAuth",
 *             description="API key"
 *         )
 *     )
 * )
 */
public function cgetAction(): Response
{
    // ...
}

不是在类级别添加@SWG\SecurityScheme 注释，也不是在@SWG\Get 旁边添加注释，而是将其放置在请求注释块中并将其包装在@SWG\Swagger 块中以显示安全定义。

尽管如此，这还不够，因为它涉及大量重复，而且 swagger-php 失败并出现重复定义错误。

因此，我创建了一个通用索引控制器，它除了提供安全方案注释之外什么都不做。虽然这感觉远不是真正的解决方案，但它现在解决了这个问题。

这是虚拟控制器：

<?php

namespace App\Controller\Api;

use FOS\RestBundle\Controller\Annotations\Route;
use FOS\RestBundle\Controller\FOSRestController;
use FOS\RestBundle\Routing\ClassResourceInterface;
use Swagger\Annotations as SWG;
use Symfony\Component\HttpFoundation\Response;

class IndexController extends FOSRestController implements ClassResourceInterface
{

    /**
     * @Route("/")
     * @SWG\Get(
     *     security={
     *         {"ApiKeyAuth":{}}
     *     },
     *     @SWG\Response(
     *         response=200,
     *         description="Returns 200 if the request was authorized",
     *     ),
     *     @SWG\Response(
     *         response=401,
     *         description="Returns 401 if the X-API-KEY header is missing or the provided token is not valid"
     *     ),
     *     @SWG\Swagger(
     *         schemes={"https"},
     *         @SWG\SecurityScheme(
     *             name="X-API-KEY",
     *             type="apiKey",
     *             in="header",
     *             securityDefinition="ApiKeyAuth",
     *             description="API key"
     *         )
     *     )
     * )
     */
    public function getAction(): Response
    {
        return $this->handleView($this->view(null, Response::HTTP_OK));
    }

}