Question

我们可以define components in Swagger：

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'

它给我一个错误：

处理异常时引发的异常（Symfony \ Component \ Config \ Exception \ FileLoaderLoadException：在。（从“ /app/config/routes/api_platform.yaml”导入的）中找不到资源“ components”。有一个支持“ api_platform”类型的加载器。）

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

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

Answer 1

您不能那样做。

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

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

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

有可能...参见How can I annotate my attribute which is Value Object in order that API Platform would generate its fields for swagger documentation?

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

 * @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声明组件？

2 个答案: