如何从 @SWG\Response 中使用的模型中排除某些（嵌套的）属性

Question

我在PhpLaravel中写API，使用swagger(2.0)注解(lib:darkaonline/l5-swagger which use swagger-php)生成swagger.json。我有以下招摇：

@SWG\Definition(
    definition="Space",
    @SWG\Property( property="id", type="integer", example=33),
    @SWG\Property( property="name", type="string" ),
    @SWG\Property( property="dataA", type="string", example="very long data string" ),
    @SWG\Property( property="dataB", type="string", example="very long data string" ),
),

@SWG\Get(
    path="/api/v1/client/space/list",
    @SWG\Response( response=200, description="OK", 
        @SWG\Schema(
               type="array", 
               @SWG\Items(ref="#/definitions/Space"), 
        )
    )
)

以上 api 应该 return Spaces 列表（显示在 table 中）但我只需要得到 id 和 name - 但是 Space 也有很重的字段 dataA 和 dataB - 在 table 中不需要。有没有办法在不为响应创建单独的 Space 定义的情况下排除这些字段（以避免违反 "don't repeat yourself" 规则）？有没有一些机制可以做这样的事情：

@SWG\Items(ref="#/definitions/Space", exclude={"dataA","dataB"}),

And/or 排除更多嵌套字段，例如

exclude={"dataA.securityField","dataA.someList[].heavyField"}

?

PS：我也将其报告为 question/issue here。

Answer 1

目前不存在排除等功能的实现（查看 here）。但是，您可以尝试遵循部分可接受的方法（您创建了新定义，但此定义重用了 Space 定义的部分内容）：

@SWG\Definition(
    definition="SpaceListEntry",
    @SWG\Property( property="id", ref="#/definitions/Space/properties/id" ),
    @SWG\Property( property="name", ref="#/definitions/Space/properties/name" ),
)

并在 @SWG\Get 中将 @SWG\Items(ref="#/definitions/Space"), 更改为

@SWG\Items(ref="#/definitions/SpaceListEntry"),

此解决方案部分令人满意，但优于 Space 定义的完整副本。

如何从 @SWG\Response 中使用的模型中排除某些（嵌套的）属性

How to exclude some (nested) properties from models used in @SWG\Response

php

annotations

swagger-php

swagger-2.0