README

从注释的 PHP 源文件生成 RAML 文档。

RAML 是一种用于描述 RESTful API 的建模语言，它是与 API 一起提供的补充文档。为了避免实现和文档随着时间的推移而分离，这个库提供了根据实现 API 的注释源代码文件生成 RAML 文档的功能。

这并不能完全解决问题，因为注释也需要保持更新。作为回报，它们与代码更加紧密耦合，并位于同一文件中，这有望使它们更有可能得到更新。

用法

生成 RAML 文档的过程包括两个过程：首先，解析源代码文件并查找文件和方法级别文档块中的合适注释。其次，根据解析器在源代码文件中找到的数据创建一个新的 RAML 文档。

解析

要查找源文件中的相关 RAML 注释，请使用 Parser 类进行解析。

$annotations = Parser::process(
    '/path/to/class.php'
);

process 方法返回一个 FileAnnotations 对象，它返回文件、类、成员、方法和属性级别的文档块中的注释。

支持在文件级别上的注释有

• 标题

  REST API 的标题。标题注释还用于合并相关的源文件，这在 API 实现代码组织在多个文件中时是必要的。

• 版本

  REST API 的版本。

• BaseUri

  所有资源请求基于的基本 URI。可能包含 RAML 规范中记录的变量部分，例如 "https://api.example.com/{version}"。

• MediaType

  响应编码的媒体类型，例如 "application/json"。

• 协议

  用于访问 API 的协议，例如 "HTTPS"。如果支持多个协议，则根据需要添加多个协议注释标签。

• SecurityScheme

  描述支持的方案。如果支持多个安全方案，则根据需要添加多个注释标签。例如，基本认证：name="basic"，type="Basic Authentication"。

包含 RAML 特定注释的文件级别文档块示例

/**
 * @\raml\annotations\Title(title="Karmap Core API")
 * @\raml\annotations\Version(version="v1")
 * @\raml\annotations\BaseUri(baseUri="https://api.core.karmap.com/{version}")
 * @\raml\annotations\MediaType(mediaType="application/json")
 * @\raml\annotations\Protocol(protocol="HTTPS")
 * @\raml\annotations\SecurityScheme(name="basic", type="Basic Authentication")
 */
 
/**
 * Class-level docblock
 */
class AClass {
   ...
}

在指定关于 REST API 的一般信息后，我们现在继续描述 API 包含的操作。在大多数情况下，REST API 调用将映射到类函数，即方法。因此，需要使用以下在方法级别支持的特殊标签对方法进行注释

• 资源

  指定在基本 URI 后的 URI 部分，该部分用于命名资源，例如 "/albums"。

• HttpVerb

  用于访问资源的 HTTP 动词，例如 "POST"。

• 描述

  资源或操作的描述。

• SecuredBy

  在此处使用在文件级别的安全方案标签中定义的安全方案之一，例如 "basic"。

• 参数

  使用多个参数注释标签指定 REST API 操作所需的全部参数。请参阅以下源代码片段的示例。

...
class AClass {
    ....
    
    /**
     * @\raml\annotations\Resource(resource="/anonymousInterpretations")
     * @\raml\annotations\HttpVerb(verb="POST")
     * @\raml\annotations\Description(description="Create anonymous interpretation")
     * @\raml\annotations\SecuredBy(scheme="basic")
     * @\raml\annotations\Parameter(
     *   parameterType="form",
     *   name="clientCode",
     *   displayName="Client code",
     *   description="Code identifying the client",
     *   type="string",
     *   pattern="^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
     *   required="true",
     *   example="b4762505-b108-46a0-a4c7-f79c4b224b58"
     * )
     */
    public function doSomething(...) {
    }

    ...
}

生成

要生成 RAML 文档，请使用 Generator 类。