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

Posted 2023-02-16

【中文标题】Symfony、nelmio/api-doc-bundle 和 @SWG\\SecurityScheme

【英文标题】：Symfony, nelmio/api-doc-bundle and @SWG\SecuritySchemeSymfony、nelmio/api-doc-bundle 和 @SWG\SecurityScheme

【发布时间】：2018-06-17 00:08:26

【问题描述】：

我正在尝试使用 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 以识别具有全局定义的文件吗？

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

真的有用吗？

【参考方案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));