如何解决API 平台 - 自定义控制器/动作描述注释不起作用
如果我在这里遗漏了一些东西,真的很抱歉,但我已经搜索了很多问题和文档,但我找不到为什么这不起作用。也许我需要另一个关于使用互联网的教程 ;)
考虑下面的实体注解,在clock.schedule_unique(anim_right,0.5)
部分的openapi_context
和body.description
根本没有任何作用,这让我有点生气......你应该知道我是使用去/标准化上下文,但这似乎并不相关,所以我将其排除在外。
responses.200.description
我在这个问题上花了太多时间,如果有人能帮我解决这个问题,我真的很感激。我已经检查/尝试了以下无济于事;
- Creating Custom Operations and Controllers
- Custom Symfony Action with API Platform bundle
- [Question] Documentation API with Swagger #143
- Changing Operations in the OpenAPI Documentation
作曲家版本(相关部分):
/**
* User entity
*
* @API\ApiResource(
* collectionoperations={
* "authenticate"={
* "method"="POST",* "status"=200,* "path"="/authenticate",* "controller"=UserLoginController::class,* "openapi_context"={
* "responses"={"200"={"description"="API token and secret"}},* "body"={"description"="Login details"},* "summary"="User authentication",* "description"="Provides auth tokens on success",* },* },* }
* )
*
*/
class User implements UserInterface
{
...
}
解决方法
经过一些试验,我发现 openapi_context
注释属性确实似乎忽略了响应文档。但是,它确实允许您提供您缺少的请求正文描述:
#[ApiResource(
collectionOperations: [
'test' => [
'method' => 'POST','path' => '/test','openapi_context' => [
'summary' => 'The endpoint summary','description' => 'The endpoint description','requestBody' => [
'description' => 'The endpoint request body description',// This one
'content' => [
'application/json' => [
'schema' => [
'$ref' => '#/components/schemas/MyResource-some.group'
],],]
],)]
我在编写本文时使用 PHP 8.0.3
和 API 平台 2.6.3
,但将注释更改为 docblocks 应该会为您带来相同的结果。
然而,为了记录端点响应规范,我必须实现一个自定义的 OpenApiFactoryInterface:
<?php declare(strict_types = 1);
namespace App;
use ApiPlatform\Core\OpenApi\Factory\OpenApiFactoryInterface;
use ApiPlatform\Core\OpenApi\Model\Operation;
use ApiPlatform\Core\OpenApi\Model\PathItem;
use ApiPlatform\Core\OpenApi\Model\RequestBody;
use ApiPlatform\Core\OpenApi\OpenApi;
use ArrayObject;
use UnexpectedValueException;
class MyResourceOpenApiFactory implements OpenApiFactoryInterface
{
private OpenApiFactoryInterface $openApiFactory;
public function __construct(OpenApiFactoryInterface $openApiFactory)
{
$this->openApiFactory = $openApiFactory;
}
public function __invoke(array $context = []): OpenApi
{
$openApi = ($this->openApiFactory)($context);
$components = $openApi->getComponents();
$schemas = $components->getSchemas();
if (null === $schemas) {
throw new UnexpectedValueException('Failed to obtain OpenApi schemas');
}
$pathItem = new PathItem(
'MyResource test endpoint','A test summary','A test description',null,// Your custom post operation
new Operation(
'testMyResourceCollection',// the operation route name
[
'MyResource' // your resource name
],[
// response specifications
'201' => [
'description' => 'test endpoint 201 response description','content' => [
'application/json' => [
'schema' => [
'$ref' => '#/components/schemas/MyResource-read',// your resource (read) schema
],'A test endpoint summary','A test endpoint description',[],new RequestBody(
'A test request body description',new ArrayObject([
'application/json' => [
'schema' => [
'$ref' => '#/components/schemas/MyResource-write',// your resource (write) schema
],]),),);
$paths = $openApi->getPaths();
$paths->addPath('/my_resources/test',$pathItem);
return $openApi;
}
}
让这个 OpenApiFactoryInterface
实现由服务容器作为装饰器连接到 api_platform.openapi.factory
:
App\MyResourceOpenApiFactory:
decorates: 'api_platform.openapi.factory'
autoconfigure: false
将对示例 MyResource
名称的引用更改为您选择的资源名称(如 User
)。
旁注: 在我看来,在 API 平台中自定义 OpenApi 端点文档的整个过程目前非常复杂。使用我提供的实现作为您自己实现的参考,因为您很可能需要对其进行一些调整,使其满足您的特定用例。
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。