README

此软件包将 PHP 方法文档注释转换为用于与 mashery/iodocs 一起使用的 backplane.json 文件。它使用注解来确定如何为每个 API 端点填写详细信息。

注意！

在此，我将列出在使用此软件之前您可能需要注意的重要事项。

Doctrine 注释解析器不支持空数组，因此如果您在文档中使用它，将会遇到解析异常。

设置

独立运行

克隆存储库，然后在您的终端导航到它。运行 php composer.phar install，然后您就成功了。

Composer 依赖项

将 backplane/apidoc-generator 添加到您的 composer.json 文件中，运行 composer install。现在您可以从 vendor/bin/iodocsgen 运行它。

将 PHPDocs 转换为 IODocs

这样运行生成器

path/to/iodocsgen [--iodocs] path/to/api/ output.json

可以省略 --iodocs 标志 - 默认情况下会使用它。

有效的修饰符

在生成 iodocs 时，这些标志是有效的

--bootstrap|b path/to/bootstrap.php：在生成文档之前从该 PHP 文件启动。
--config|c path/to/config.json：包含更多参数的 json 文件。

使用配置运行

在配置文件中，您可以指定以下选项

api：要文档化的 API 的字符串路径
output：输出的文件路径
bootstrap：字符串，与上述 bootstrap 修饰符相同。
bootstrap_args：对象，传递给启动的参数的哈希，这些参数可通过启动文件中的 $params 数组访问。
exclude：要忽略的 API 目录内的路径数组
dependencies：要包含但不考虑文档的路径数组（只要它们不在 api 路径之外）

如果您使用 api 和 output 标志，则可以在调用工具时省略这些参数。

示例 JSON 配置

{
  "api": "/path/to/api",
  "output": "/path/to/output/file",
  "exclude": [
    "file/to/exclude.php",
    "directory/to/exclude",
    "another/directory/to/exclude/",
  ],
  "bootstrap": /path/to/bootstrap.php,
  "dependencies": [
    "/path/to/dependency.php"
  ]
}

相对路径

在 exclude 和 dependencies 中的所有路径都是相对于 API 位置的。
当 bootstrap 作为命令行标志指定时，它是相对于当前工作目录的。当在配置中指定时，它是相对于配置文件位置的。

参数与配置优先级

api 和 output 是必需的，要么两者都在配置文件中设置，要么都作为程序的参数提供。如果任何参数在配置文件和程序调用中都有，则参数将覆盖配置值。例如，在配置文件中和调用时都定义了 [--bootstrap|-b] 标志，将优先选择标志，如果将 api 和 output 在配置中定义并提供 2 个参数来调用程序，则选择程序参数。

类文档注释

首先，包含您的 API 端点的 php 文件应在顶部包含此 use 语句，以处理正确的命名空间

<?php
use Backplane\APIdocGenerator\Annotations;

// ...

@Annotations\Endpoint 注解不仅告诉文档生成器考虑此类及其方法，而且还具有一个必需的 name 参数，该参数编码了端点名称

/**
 * @Annotations\Endpoint(name="Posts")
 */
class postsCall extends apiCall {
    // code...
}

API 文档注释

将 @Annotations\EndpointMethod 放置在表示端点方法的函数上。此注解还有更多字段

/**
 * @Annotations\EndpointMethod(
 *   name="Method name",
 *   description="This is the method description.",
 *   URI="/path/to/endpoint/method.php",
 *   HTTPMethod="GET",
 *   requiresOAuth=true,
 *   parameters={ ... }
 * )
 */

API 参数注解

@Annotations\Parameter 注解仅对 @Annotations\EndpointMethod 的 parameters 字段有效。这是其形式

/**
 * @Annotations\Parameter(
 *  name="Parameter name",
 *  description="Parameter description",
 *  type="int",
 *  required=false,
 *  default=0
 * )
 */
)

或者，如果 type 字段是 enum，则还有两个更多必需字段

/**
 * ...
 * type="enum",
 * enum={ ... }
 * ...
 */

最后，enumList 字段是 @Annotations\Enum 对象的列表，其形式如下

/**
 * @Annotations\Enum(
 *  name="Enumeration name",
 *  description="This field is optional."
 * )
 */

（如上所述，描述字段是可选的。）

这就结束了！现在开始编写文档吧！

示例文档以生成有效的 IODocs

<?php
use Backplane\APIdocGenerator\Annotations;

/**
 * @Annotations\Endpoint(name="Posts")
 */
class Posts {
    /**
     * This text is not parsed by the Doctrine Annotations parser.
     *
     * @Annotations/EndpointMethod(
     *   name="getIndex",
     *   description="This gets the hot posts.",
     *   URI="/posts.:format",
     *   HTTPMethod="GET",
     *   requiresOAuth=true,
     *   parameters={
     *     @Annotations/Parameter(
     *       name="offset",
     *       description="Offset from first result",
     *       type="int",
     *       required=false,
     *       default=0
     *     ),
     *     @Annotations/Parameter(
     *       name="limit",
     *       description="Maximum number of results",
     *       type="int",
     *       required=true,
     *       default=100
     *     ),
     *     @Annotations/Parameter(
     *       name="type",
     *       description="Type of post",
     *       type="enum",
     *       enum={
     *         @Annotations/Enum(
     *           name="Photo",
     *           description="A photo post"
     *         ),
     *         @Annotations/Enum(
     *           name="Text",
     *           description="A text post"
     *         ),
     *       },
     *       required=true,
     *       default="Text"
     *     )
     *   },
     * )
     */
    public function getIndex()
    {
        // code here...
    }
}

将现有 IODocs 转换为 PHPDocs

此脚本也可以在相反方向上进行转换。然而，由于它不知道您的代码结构，因此它所做的一切只是将您现有 API 的所有相应 PHPDocs 注释转储到文件中。

要使用此功能，请运行以下命令

/path/to/iodocsgen --phpdocs /path/to/iodocs/data.json outputfile.php

计划更新

一旦我在 IODocs 中实现了返回类型功能。
测试没有提供完整的覆盖范围，而且不幸的是并不清晰。但它们应该检查大多数功能。这应该得到改善。

祝您露营愉快！

backplane / apidoc-generator

维护者

详细信息