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

现在问题是我需要在任何地方定义ApiKeyAuth。基于我发现的例子......

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

}

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

1 个答案: