如何在 API 平台中使用“$ref”引用和声明来自 Swagger 的组件？

Question

components:
  schemas:
    User:
      properties:
        id:
          type: integer
        name:
          type: string

并稍后使用此组件：

responses:
  '200':
    description: The response
    schema: 
      $ref: '#/components/schemas/User'

我想使用它以避免重复内容。

我尝试在 API 平台中使用此语法：

components:
    schemas:
        Part:
            description: Array of Part
            type: array
            items:
                type: object
                properties:
                    name:
                        type: string

App\Entity\Item:
    collectionOperations:
        post:
            method: 'POST'
            swagger_context:
                parameters:
                    - name: body
                      description: Item data
                      in: body
                      schema:
                          type: object
                          properties:
                              name:
                                  description: Part
                                  type: string
                                  required: true
                              part:
                                  $ref: '#/components/schemas/Part'

它给我一个错误：

Exception thrown when handling an exception (Symfony\Component\Config\Exception\FileLoaderLoadException: Resource "components" not found in . (which is being imported from "/app/config/routes/api_platform.yaml"). Make sure there is a loader supporting the "api_platform" type.)

YAML 加载程序似乎无法识别 components 项。

如何在 API 平台中定义和使用引用？如何定义引用并在多个 YAML 文件中使用它？

Answer 1

你不能这样做。

components键属于Swagger/OpenAPI格式，不属于API平台配置（映射）格式。 API 平台配置文件和 Swagger 定义都可以用 YAML 编写，但它们没有关系。

因此，如错误消息所述，Swagger components 无法像您尝试的那样直接注入 API 平台的配置文件。

API 平台的配置确实允许使用 swagger_context 键在生成的 Swagger 文件中注入一些上下文，但是您不能编写随机的 Swagger 定义（例如您的 component 键) 在此结构之外。

要实现你想做的事情，swagger_context 键是不够的（组件必须注入到 Swagger 文件的根目录，而 swagger_context 是不可能的）。

您必须为 Swagger 文档生成器创建装饰器，而不是使用此键，如本文档条目中所述：https://api-platform.com/docs/core/swagger/#overriding-the-swagger-documentation

Decorator 允许访问整个 Swagger 结构，并对其进行修改。这样您就可以添加 components 结构。

Answer 2

有可能……参见

在我的例子中，我有实体检查器，我创建了两个组：

 * @ApiResource(
 *     attributes={
 *          "normalization_context"={"groups"={"read"}},
 *          "denormalization_context"={"groups"={"write"}},
 *     },

然后在 swagger_context 回复中：

 *                  "responses" = {
 *                      "201" = {
 *                          "description" = "....",
 *                          "schema" =  {
 *                              "type" = "object",
 *                              "properties" = {
 *                                   "myresult" = {
 *                                      "$ref"="#/definitions/Checker-read"
 *                                   }

如何在 API 平台中使用“$ref”引用和声明来自 Swagger 的组件？

How to use "$ref" reference and declare components from Swagger in API platform?

symfony

api-platform.com