问题描述
我正在尝试使用 nelmio/api-doc-bundle 记录我的Symfony 3.4应用程序API，但是无法创建安全方案.
I'm trying to document my Symfony 3.4 application API using nelmio/api-doc-bundle but fail to create a security scheme.
使用以下配置，生成文档本身可以按预期工作:
Generating the documentation itself works as expected with the following configuration:
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文件:
So I get a proper JSON file like this:
{
"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.根据我发现的例子...
Now the problem is that I need to define ApiKeyAuthanywhere. Based on the examples I found ...
https://github .com/zircote/swagger-php/blob/master/Examples/petstore.swagger.io/security.php
https://swagger.io/docs/specification/2-0/authentication/api-keys/
...可能类似于以下内容:
... that might look like the following:
/**
* @SWG\SecurityScheme(
* name="X-API-KEY",
* type="apiKey",
* in="header",
* securityDefinition="ApiKeyAuth"
* )
*/
但是无论我将其放在控制器中的什么位置，都无法识别.
But regardless of where I put this in the controller it is not recognized.
那么合适的地方在哪里?
我可以配置api-doc-bundle以识别具有全局定义的文件吗?
Can I configure the api-doc-bundle to recognize a file with global definitions?
我需要在配置中创建定义而不是作为注释吗?
Do I need to create the definition in the config and not as annotation?
它完全可以工作吗?
推荐答案
...
/**
* @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\Get旁边添加@SWG\SecurityScheme注释，而是将其放置在请求注释块中并将其包装在@SWG\Swagger块中，从而显示安全性定义.
Instead of adding the @SWG\SecurityScheme annotation at class level, or alongside @SWG\Get, placing it inside the request annotation block and wrapping it in a @SWG\Swagger block made the security definition show up.
但是，这还不够，因为它涉及很多重复，而且swagger-php失败，并出现重复定义错误.
Nevertheless, this was not sufficient as it involves a lot of duplication, and, moreover swagger-php fails with a duplicate definition error.
因此，我创建了一个通用索引控制器，该控制器除了提供安全方案注释外不执行其他操作.尽管这远非实际的解决方案，但目前已解决了该问题.
Thus I created a generic index controller which does nothing else but providing the security scheme annotation. Though this feels far from being the actual solution it solved the issue for now.
这是虚拟控制器:
<?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的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！