README

使用接口和可选Swagger实现的SilverStripe外观模式API实现。

简介

这是一个有观点的包，它实现了一个具有以下功能的SilverStripe API

每个API节点都在PHP接口文件中进行了描述。
API从您的SilverStripe数据结构中抽象出来。

您可以根据对消费者的最大逻辑意义来结构化您的API：这是外观模式。

可选的Swagger UI实例集成。
每个接口的可选存根文件实现，用于测试。
每个接口的实际实现可以分配给任何（一个）类。

在许多情况下，实现接口的类可能是一个现有的页面控制器，但您可以完全自由地有一个单独的类仅用于实现API接口。

此包正在由Govt.nz团队逐步开发，并且正在添加所需的功能。

这意味着一些期望的功能尚未实现。

例如，OAuth和权限检查只有在我们需要时才会添加。

快速入门

composer require govtnz/silverstripe-api

此模块中的/resources/data_dir子目录包含接口示例。

将整个子目录复制到合适的位置（见下面的API数据）。
运行dev/build。
运行dev/tasks/ApiRebuildDefinitionsTask。
在浏览器中，键入[WEBROOT]/api/v1/section/list ... 您应该看到正确格式的响应。

使用Swagger-UI或手动浏览assets/api/v1/swagger.json文件，了解其他可用的API请求。

配置

GovtNZ\SilverStripe\Api\ApiManager:
    api:
        v1:
            definition: 'path/to/base.txt'
            interfaces:
                - ApiInterfaceOne
            stubs
                - ApiInterfaceStubOne
        v2:
            definition: 'path/to/base.txt'
            interfaces:
                - ApiInterfaceOne
            stubs
                - ApiInterfaceStubOne

API定义

silverstripe-api 允许您将API定义分解为分布在多个文件中的块。

分割您的API定义不是强制性的：如果您愿意，您可以将其编写为单个块。但是，分割它提高了可维护性，并且开发任务API：重建定义仍将为每个API版本生成单个swagger.json文件。

但是您如何结构化您的API定义，它需要是

标准的JSON，
与Swagger 2.0规范一致，并且
包含在多行注释块中
```
/* 

  (json here) 
  
*/
```

与常规JSON文件不同，您可以在API定义中包含//注释（但不要使用/* */注释）。这些//注释将被生成swagger.json输出的开发任务忽略。开发任务将假设每个JSON块是Swagger定义中的顶级元素：提供的示例演示了这一点。

Swagger JSON文件

开发任务API：重建定义从每个接口中提取JSON片段，并将它们构建成一个单一的swagger.json文件。

默认情况下，生成的swagger.json文件保存在/assets/api中，但您可以使用.yml配置设置来更改它

Swagger:
  data-dir: [PATH]

并且如果您将govtnz/swagger-ui与该API模块集成，则此路径必须是外部可访问的。

定义文件

每个API目录必须有一个文件，它定义了所有接口节点共有的属性。

在此文本文件中，有两个有用的变量可用于在开发、测试和生产服务器之间使API定义更便携

您可以使用getHost自动填充“host”键

"host": "<% getHost %>",

您可以使用getProtocol自动填充“schemes”数组

"schemes": [
    "<% getProtocol %>"
],

建议您复制并修改现有的 resources/base.txt 文件，以启动自己的 API 开发。

测试

可以编写自动化测试来测试每个接口及其存根文件。这些测试可以存储在 /tests 子目录中。

stubs 目录中的每个文件都使用静态数据实现 API 接口。它在以下两种情况下之一被调用：

当在 API 请求中添加 test 参数时，例如 &test=true。
当没有其他 API 接口的实现时。

存根文件不是强制性的，但它们对测试很有用，因为它们的响应永远不会改变。

API 文档

ApiController 中有几个有用的函数

caseCamel($field) 确保字段 $field 是驼峰命名。
caseRequest($field) 确保字段 $field 符合请求中指定的格式（默认为驼峰命名）。简单的一个单词字段名在驼峰和蛇形命名法中相同，但更复杂的字段名可以在生成输出时通过此函数传递。
caseSnake($field) 确保字段 $field 是蛇形命名。
date3339toDB($input) 将 RFC3339 时间戳（2015-06-28T00:00:00+12:00）转换为 MySQL 格式（2015-06-28 00:00:00）。
dateDBto3339($input) 将 MySQL 时间戳（2015-06-28 00:00:00）转换为 RFC3339 格式（2015-06-28T00:00:00+12:00）。
formatOutput() 返回一个包含两个节点的数组：查询总数、计数和偏移量；之前分配给 output 的输出数据。
logAdd($text) 填充控制器的内部日志；有时对调试很有用。
logGet() 返回控制器的内部日志作为一个数组；有时对调试很有用。
param($name) 返回请求参数 $name，如果不存在则返回空字符串。
setError($params) 接受一个包含 status 值和一个或多个错误信息的数组。它更改控制器的状态并设置要返回的错误信息。
xmlAdd($key, $parent, $label) 为给定的键|父组合注册一个 XML 标签。可以使用星号 * 来表示数值。注册标签仅对通用规则的例外情况是必要的，即 XML 标签复数将通过添加 "s" 来创建。然而，一个重要的用例是一维数组，它将具有数字键。默认行为是将任何数字键转换为 "item"，以防止 XML 解析错误，但具有上下文特定的标签会更好。

实现

您的实现代码可以

依赖于字段名是驼峰命名。
从控制器的 param() 函数中检索请求参数。
使用 date3339toDB() 和 dateDBto3339() 转换请求和响应日期。
使用 xmlAdd() 注册 XML 节点的标签。
如果无法处理请求，请调用控制器的 setError() 函数。

您的实现必须

对任何超过简单一个单词名的输出字段调用 caseRequest()。
将生成数据作为数组分配给控制器的 output 属性。
如果输出数据的类型与 API 节点的基类型不同，请设置控制器的 pronoun 属性。

例如，API 方法 organisation/sector 返回组织部门的列表，而不是组织的列表。在这种情况下，将 pronoun 设置为 sector，以便输出得到适当的描述。

Swagger 集成

有一个配套的包，govtnz/swagger-ui，它派生了 Swagger UI，使得在 SilverSripe 项目中包含它变得容易。

有关更多详细信息，请参阅此配套 Swagger 包中的文档。

govtnz / silverstripe-api

维护者

详细信息