ApiPlatform中如何使用同名基类名的多个资源？

问题1：是否必须重命名资源类？ #

• 不是必须，重命名是最直观的方案，但你也可以通过自定义OpenApi Schema名称保留原类名。
• 实现方式：在每个资源类的ApiResource注解中指定openapiContext，自定义schema的标题和名称：

  // Foo\Item.php
  #[ApiResource(
      openapiContext: [
          'schema' => [
              'title' => 'FooItem',
              'name' => 'FooItem'
          ]
      ]
  )]
  class Item { /* ... */ }
  
  // Bar\Item.php
  #[ApiResource(
      openapiContext: [
          'schema' => [
              'title' => 'BarItem',
              'name' => 'BarItem'
          ]
      ]
  )]
  class Item { /* ... */ }
  

• 配置后文档会生成两个独立的FooItem和BarItem schema，无需修改类名。

问题2：能否按命名空间分组生成独立文档？ #

• 可以，ApiPlatform支持多文档分组，有两种常用实现方式：

1. 基于资源分组配置

   • 给不同命名空间的资源设置专属分组标识：

     // Foo\Item.php
     #[ApiResource(groups: ['foo'])]
     class Item { /* ... */ }
     
     // Bar\Item.php
     #[ApiResource(groups: ['bar'])]
     class Item { /* ... */ }
     

   • 在config/packages/api_platform.yaml中配置多个OpenApi实例，分别对应不同分组：

     api_platform:
         openapi:
             versions: [3.0]
             foo:
                 title: 'Foo API'
                 path_prefix: '/api/foo'
                 groups: ['foo']
             bar:
                 title: 'Bar API'
                 path_prefix: '/api/bar'
                 groups: ['bar']
     

   • 访问/api/docs/foo和/api/docs/bar即可查看各自独立的文档。

2. 基于路由前缀过滤

   • 如果资源已经按路由前缀区分（比如/api/foo和/api/bar），可直接通过path_prefix过滤生成独立文档，无需设置资源分组：

     api_platform:
         openapi:
             versions: [3.0]
             foo:
                 title: 'Foo API'
                 path_prefix: '/api/foo'
             bar:
                 title: 'Bar API'
                 path_prefix: '/api/bar'
     

问题3：此情况是否属于Bug？是否应抛出冲突错误？ #

• 这不属于Bug，是ApiPlatform的默认设计行为：它默认使用类的短名称（如Item）作为OpenApi Schema的名称，当存在同名类时，后加载的会覆盖先加载的（按字母顺序处理）。
• 但从开发者体验角度，确实应该添加冲突检测机制，提醒用户存在同名Schema的覆盖问题。目前官方没有内置这个检测，你可以在ApiPlatform的GitHub仓库提交Feature Request，建议添加该功能。

内容的提问来源于stack exchange，提问作者Alex Howansky