【Day 22】Google Apps Script - API Blueprint 篇 - API Blueprint 格式范例

以「查询Gamil资讯」API 文件为范例，介绍 API Blueprint 格式 —— 这是一个简单的 API，允许查看 Jason Gmail 信箱的前 5封信。

今日要点：
》API Blueprint 格式介绍

API Blueprint 格式介绍

创建 Blueprint 的第一步是指定 API 名称和 Metadata。此步骤如下所示：

Metadata

Blueprint 从 Metadata 部分开始。

HOST: https://script.google.com
FORMAT: 1A

在本例中，我们指定 FORMAT 的值为 1A。FORMAT 关键字表示 API blueprint 的版本，版本的资讯可以参考这里，如下图红色虚框的地方：

API Name & Description

Blueprint中的第一级标题 # 後面就是 API 的名称，之後就是 API 描述，可以用 markdown 的语法写。不过通常我们会先用 Group 来包起来。
　

Resource Groups (资源群组)

在标题# 後使用 Group 关键字，可以建立了一组相关资源。

# Group API文件Demo 

Resource (资源)

就是指单一个 API，像在 Group API文件Demo 资源群组中，我们有一个名为 查询Gmail资讯 的资源。 此资源允许查看 Jason Gmail 信箱的前 5封信。 标题末尾的方括号内，是的资源访问的 URI。

## 查询Gmail资讯[/macros/s/AKfycbyLOQLi_p2I2y0TQ4IrQ8vV53rtMSRdunWLqFJB5pBhHG9frBOf7rKB0Yunfl6x1twr/exec{?name,func}]

Actions(动作)

API Blueprint 允许我们指定可能对资源执行的每个操作。一个动作是用资源内的子标题指定的，该子标题後跟 HTTP 方法的动作名称。

### try:查询Gmail资讯 [GET]

一个动作应该至少包含一个来自服务器的响应，它必须包含一个状态代码并且可能包含一个正文。 响应被定义为操作中的列表项。 列表是通过在列表项前面加上 a、* 或 - 创建的。

此操作会返回 200 状态代码和 JSON 正文。

+ Response 200 (application/json)

URI Template(模板)

就是上面方括号里 URI 中的 {?name,func}
　

URI Parameters(参数)

URI Parameters应该使用参数表来描述 URI。对於 查询Gmail资讯，它将如下所示：

• Parameters
  • name: Jason (string, optional) -查询人的姓名
  • func: getGmailInfo (string, required) - 要呼叫的功能名称

完整的范例

API描述的部份我稍微精简一点，阅读起来不会太长。

HOST: https://script.google.com
FORMAT: 1A

# 铁人赛 2021 
## Version
v1.0


# Group API文件Demo

## 查询Gmail资讯 [/macros/s/AKfycbyLOQLi_p2I2y0TQ4IrQ8vV53rtMSRdunWLqFJB5pBhHG9frBOf7rKB0Yunfl6x1twr/exec{?name,func}]
<table>
    <tr>
        <th>Docs Demo</th>
        <th>getGmailInfo</th>
        <th>查询Gmail资讯</th>
    </tr>
    <tr>
        <td>说明</td>
        <td colspan=2> 使用 Google Apps Script 查询 Gmail 资讯。</td>
    </tr>
</table>

### try:查询Gmail资讯 [GET]
+ Parameters
    + name: Jason (string, optional) -查询人的姓名
    + func: getGmailInfo (string, required) - 要呼叫的功能名称

+ Response 200 (application/json)

参考

• API Blueprint Tutorial
• 设计API时好用的工具 - 让前後端沟通格式不再卡卡 - API Blueprint基本结构介绍篇