文档地址

• 员工端

• 活动端

• 控制台

这是什么？

这是零售帮项目的 API Specification，它使用 OpenAPI 来描述一个 api 的 url，请求体，请求头，返回头，返回体等。有了这个描述文件，就可以 mock 数据，生成代码，或者用来做 数据校验，测试等等。

for more detail: https://swagger.io/specification/

部署文档和包

生成文档

文档是给前后端开发看的，生成文档依赖 redoc-cli，首先安装 redoc-cli：

npm i redoc-cli -g

之后生成并且部署文档到 dev 服务器，请先测试 dev 服务器能否正常登陆，如果不行请添加 ssh 公钥或者更改部署地址。

ssh [email protected]

登录成功后运行：

npm run deploy

发布版本

npm 包，是用来生成代码以及 mock 数据的

要发包，请先确保你已经登录 npm，运行

npm login

再确认你有发包的权限，如果没有请让管理员邀请你加入 npm 的@jukeplus 组织

最后运行

npm run pub

为什么？

其实 API Specification 是个比较重要的东西，api 是项目的桥梁，所以保持一致性能够避免很多问题。

何为一致性？例如，你写了一份文档，前端照着文档写了代码，后端照着文档写了代码，测试测 api 时照着文档又写了一份代码。

这样，三个人有一份文档三份代码，他们都是靠人来维持一致，人会出错， 所以会出现下面的情况：

• 后端改代码，没有改文档，没有通知前端和测试，忘了。
• 或者改了文档，代码还没上。
• 或者代码和文档没对上，字段名手残写错了。

如何避免这个问题：文档即代码。以前有代码即文档，根据代码去生成文档。但那样并不好，只是解决了不用写文档的问题。这个问题，前端、后端、测试，其实是需要一个协议（Specification）来统一规范，生成代码，用这个 Spec 来描述你的 api，然后用它来生成可读文档或者代码或者 mock 数据。这样即使手残写错，也能错得一致，运行时不会出问题。

工具

• 如果你需要使用 postman 进行测试，那么也很简单。点此查看方法

• 如果你想用这些 specs 来生成请求代码，有 openapi-generator

• 如果你想用 specs 来生成 mock 数据，有prism