如何在API-Platform v3的openapiContext中配置x-code-samples生成请求示例？

核心配置位置 #

x-code-samples 必须嵌套在 openapiContext 下的对应HTTP操作节点里——比如你要给POST请求加示例，就把它放进Post操作的openapiContext中；给GET请求加，就放进Get操作的配置里。

具体配置示例 #

以Book实体的POST请求为例，代码写法如下：

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new Post(
            openapiContext: [
                'x-code-samples' => [
                    [
                        'lang' => 'curl',
                        'source' => 'curl -X POST "https://your-api-domain.com/books" \
  -H "Content-Type: application/json" \
  -d "{\"title\": \"银河系漫游指南\", \"author\": \"道格拉斯·亚当斯\"}"'
                    ],
                    [
                        'lang' => 'JavaScript',
                        'source' => 'fetch("https://your-api-domain.com/books", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "银河系漫游指南",
    author: "道格拉斯·亚当斯"
  })
})'
                    ]
                ]
            ]
        )
    ]
)]
class Book
{
    // 实体属性定义...
}

关键注意点 #

• 每个示例是一个数组，必须包含lang（标注代码所属语言/工具）和source（示例代码内容）两个字段
• 不同HTTP方法的示例要分开配置，不能直接放在ApiResource根节点的openapiContext里
• 配置完成后，API-Platform会自动把x-code-samples注入生成的openapi.json，Redoc加载文档时会自动识别并渲染出对应的代码示例区块

验证方法 #

生成openapi.json后，找到对应paths下的目标操作节点，确认x-code-samples已正确存在。只要这个字段在OpenAPI文档里，Redoc就会按照你期望的样式展示示例。

内容的提问来源于stack exchange，提问作者Daniel P