我正在尝试使用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/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 以识别具有全局定义的文件吗?
我需要在配置中创建定义而不是作为注释吗?
它真的有效吗?