php - 在 API-Explorer/Swagger 中描述响应对象

Question

我正在使用Restler 3 的 API-Explorer，它是Swagger-UI的一个分支，我想知道是否有人找到了一种有效的方法来记录/描述 API 返回的响应 JSON 对象。显然，当您以交互方式试用 API 时，其中的一些——以“字里行间”的方式——是可用的，但我想要一些更详细地指示响应结构的方式。有没有人为此提出任何建议？

Answer 1

您可以使用@returnPHPDoc 注释来做到这一点。

例如，查看资源管理器中的速率限制 示例

GET authors.json/{id}

你会发现响应信息列表

Author ( name: string, email: string )

它来自以下设置为返回类型的类

<?php
/**
 * Dummy class, used only for creating swagger spec model (json schema)
 * look at the generated resources json to understand
 */
class Author
{
    public $name='Name';
    public $email='name@domain.com';
}