摄影师：Edward Jenner，连结：Pexels

哈啰，我们又见面了，最近肺炎疫情严重，大家尽量还是待在家里，不要帮助疫情增长了～写程式有个优点就是可以远端工作，而远端工作时，如何有效 沟通 就特别重要了，今天要跟大家分享我身为后端，在和前端人员合作的时候，所遇到的沟通问题和怎么透过 API 文件解决，那我们就开始啰～

前情提要

事情是这样子的，我在做一个留言板专案，一开始纯粹只用文字来切分版面，后来觉得太丑了，看下图你就知道有多丑，

所以就改抓 bootstrap 的样板，但是要把资料呈现到样板上，还是蛮麻烦的，首先要先把样板改成我想要的样子，会遇到很多 css 和 js 的问题，真 D 麻烦，再来，还要处理页面显示资料的逻辑，一开始我用 Django 的 Template Engine 写了一些 {% if xxx == yyy %}、{% for xxx in yyy %} 之类的逻辑，觉得「可恶，套用样板之后，让呈现画面不丑，但是换成程式码丑 QQ」

就当我边写后端逻辑、边改前端资料逻辑的时候，我就觉得不行，我看还是找个网页前端的人来帮我做好了，顺便累积一点前后端合作的经验，我就这样开始了专职后端的生活，然后顺便做起了这个小专案的 PM (Project Manager)，然后就是跳坑的开始 XD，下次把这过程写成文章，再来改这篇，总之，要告诉前端：「我开的 API 是这样的规格哦」，就需要条例式、有格式的写清楚我开出来的规格，这样前端才有依据来照着接 API 的资料。

1. 为什么需要写 API 文件？

一个人开发时，通常都是想到什么做什么，但如果有另一个人加入一起开发的话，就需要把你想的东西「文件化」，除非那个人就是你自己，不然就算你讲得再清楚，都还是有可能会漏掉一些没讲的。

每个人的认知程度不一样，尤其是在软体开发中，因为软体开发的範畴太广、变化又太快，在多人协作的时候，很常会发生你以为你讲清楚了，可是听的人却觉得很问号。

在前后端分离的概念中，后端开出 API 给前端对接，将业务逻辑的资料串起来，那么前端要怎么知道要对哪支 API 送什么参数、传什么资料呢？

1.1 最简单的方式

就是直接用讲的，可是用讲的容易忘记，而且讲错了也没有证据（如果你是故意要挖坑给人跳的话，这倒是个好方法，阿要记得不要被录音啰 XD）

1.2 第二直觉的方式

就是透过通讯软体的文字，这种方法通常都是想什么打什么，也没有固定格式，但如果双方是很熟的合作对象、而且团队就很小很小，这种方法或许还可以运作下去，反正出错了就直接骂一骂对方，然后再改就好了；还有一个缺点，就是 没有办法管理 API 的版本，容易散落在各种聊天室的聊天记录里。

1.3 当团队越来越大，只靠用讲的已经无法让每个人都知道目前的 API 版本时

现在最主流的方法，就是写 API 文件 (API doc)，作为给前端对接 API 的依据，条列式、照着大家都认同的规範去写 API 的规格，这样就不会错（除非有人眼残或写程式写到ㄎㄧㄤ掉 XD）。

虽然我这次的专案只有我和前端，总共才两个人

可是为什么还是要写 API 文件 呢？

因为之后我有可能要面对多个前端，势必需要有点写文件的经验，先练起来放。

2. 那么要怎么开始写 API 文件呢？

有很多种写 API 文件的方法，但比起方法和工具，知道要传达给看文件的人 什么内容 才是最重要的，内容不外乎是包含 API 的 url、这支 API 的作用、使用的 HTTP method、header 栏位、request body、response body 等等资讯，但新手不一定知道这些，对于新手来讲，这时候工具的价值才体现出来，因为工具可以帮你检查 API 文件中该有资讯，还可以帮你排版，产出漂漂亮亮的文件档

跟大家推荐一个线上工具：Apiary

3. 什么是 Apiary？

先给大家看结果图，用 Apiary 可以产出这样的 API 文件，是不是简洁漂亮又能清楚传达 API 的规格呢 ~

Apiary 是一个写 API 文件 的线上网站，採用一种名为 API Blueprint 的 API 文件语法，简单来说，API Blueprint 利用 Markdown 语法，目的是要用来撰写 API 文件。

等等，怎么觉得有点饶舌，既然都是语法，那么到底有什么不同！？没关係，我画了一张图来表示他们的关係（因为我第一次看到 API Blueprint 和 Apiary 这两个名词，也觉得很莫名其妙 XD）

先一层一层来了解这几个莫名其妙的名词的关係吧，首先 Markdown 是现在(2020年)一种广泛被用来作为写笔记的一种语法，用 Markdown 可以产生和 HTML 类似的元件，几乎都找得到相对应的元件

第二，而 API Blueprint 是一种写 API 文件 的语法，特色是利用了现在常见的 Markdown 语法作为基础，如果不想使用 Markdown 来写 API 文件 的话，可以使用 Swagger，这个 Swagger 是使用 YAML 语法写的，因为 API Blueprint(使用 Markdown) 和 Swagger(使用 YAML) 的出现，可以供偏好不同语法的人都可以写出 API 文件。

第三，最后 Apiary 是一种能视觉化 API Blueprint 语法的线上工具，除了 Apiary 可以视觉化 API Blueprint 语法之外，还有其他种工具能做到，这边先推荐大家使用 Apiary ~

4. 怎么使用 Apiary ?

因为文章已经越写越长了，就直接引用 U 质文章啰，可以参考这篇 设计API时好用的工具 - 让前后端沟通格式不再卡卡 - 工具使用介绍篇，简单来说，如果你已经是习惯 markdown 语法的人，那么来上手 Apiary 就很快；如果你习惯写 YAML 语法，那你就挑 Swagger 来写，至于用哪一种工具都没关係，反正目的都是一样的：「让前后端、团队沟通顺利，大家知道的 API 是一样的 API」。

5. 总结

本篇跟大家分享利用各种工具，透过撰写 API 文件达到团队认知同步的目的，最后给大家看一下 Apiary 和 Swagger 两种工具写起来的感觉吧。

Apiary 效果

左半部是编辑器，也就是撰写 Markdown 的地方，右半部是即时显示的样子，也就是最后会输出给团队看的样子。

Swagger 效果

左半部是编辑器，也就是撰写 YAML 的地方，右半部是即时显示的样子，也就是最后会输出给团队看的样子。

我是 RS，这是我的 不做怎么知道系列 文章，我们 下次见。

---

喜欢我的文章吗? 赶快来看看我都发了什么文章吧：我的文章目录欢迎阅读我的上一篇: [不做怎么知道系列之Android开发者偷学iOS的奇幻冒险 Day3] - 中离登出 #这么突然就GameOver的吗!? #系列暂停 #Android跨iOS好跨吗?欢迎阅读我的下一篇: [原来后端要知道] 什么是前后端分离？ #前端后端是什么 #软体发展历程 #软体开发思维