Contents
1. 使用postman工具测试API
1.1 postman简介
1.1.1 postman是什么
Postman是一个测试接口和http请求的开源工具，功能十分强大，它的优点如下：
- 支持各种的请求类型: get、post、put、patch、delete 等
- 支持在线存储数据，通过账号就可以进行迁移数据
- 很方便的支持请求 header 和请求参数的设置
- 支持不同的认证机制，包括 Basic Auth，Digest Auth，OAuth 1.0，OAuth 2.0 等
- 响应数据是自动按照语法格式高亮的，包括 HTML，JSON 和 XML
Postman汉化版的工作界面如下：
1.1.2 安装postman
Github项目地址：https://github.com/postmanlabs
Postman 可以单独作为一个应用安装，也可以作为 Chrome 的一个插件安装，建议选择前者。
- 单独应用安装：https://www.postman.com/downloads/
- Chrome插件安装：https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop
如果你英文不好，可选择汉化版下载：https://github.com/hlmd/Postman-cn/releases
- 方式1：Postman-..*-win64-.zip 解压直接用
- 方式2：app.zip 解压&&替换文件 应用程序目录/resources/app.asar（注意：请替换相同版本的文件）
1.2 基础知识储备
1.2.1 Web API简介及示例接口
- Web API是网站的一部分，用于与使用非常具体的URL请求特定信息的程序交互，这种请求称为API调用。请求的数据将以易于处理的格式（如JSON或CSV）返回，依赖于外部数据源的大多数应用程序都依赖于API调用。
-
以下我们使用Github的API作为示例进行测试：https://api.github.com/search/repositories?q=language:python&sort=stars
注：很多API都要求你注册获得API密钥后才能执行API调用。目前GitHub没有这样的要求，但获得API密钥后，配额将高得多。
1.2.2 Get与Post的区别
GET与POST是我们常用的两种HTTP Method，二者最直观的区别就是GET把参数包含在URL中，POST通过request body传递参数。简单粗暴的理解就是GET是明文传递数据，POST是加密传递数据。所以后者比前者安全，通常用户名密码使用POST传递。
|
1 2 3 4 5 |
(1) 从功能上讲，GET一般用来从服务器上获取资源，POST一般用来更新服务器上的资源； (2) 从REST服务角度上说，GET是幂等的，即读取同一个资源，总是得到相同的数据，而POST不是幂等的，因为每次请求对资源的改变并不是相同的；进一步地，GET不会改变服务器上的资源，而POST会对服务器资源进行改变； (3) 从请求参数形式上看，GET请求的数据会附在URL之后，即将请求数据放置在HTTP报文的 请求头 中，以?分割URL和传输数据，参数之间以&相连。特别地，如果数据是英文字母/数字，原样发送；否则，会将其编码为 application/x-www-form-urlencoded MIME 字符串(如果是空格，转换为+，如果是中文/其他字符，则直接把字符串用BASE64加密，得出如：%E4%BD%A0%E5%A5%BD，其中％XX中的XX为该符号以16进制表示的ASCII)；而POST请求会把提交的数据则放置在是HTTP请求报文的请求体中。 (4) 就安全性而言，POST的安全性要比GET的安全性高，因为GET请求提交的数据将明文出现在URL上，而且POST请求参数则被包装到请求体中，相对更安全。 (5) 从请求的大小看，GET请求的长度受限于浏览器或服务器对URL长度的限制，允许发送的数据量比较小，而POST请求则是没有大小限制的。 |
1.2.3 常见网络状态码及含义
- 1×× : 请求处理中，请求已被接受，正在处理
- 2×× : 请求成功，请求被成功处理（200 OK）
- 3×× : 重定向，要完成请求必须进行进一步处理（301: 永久性转移、302：暂时性转移、304：已缓存）
- 4×× : 客户端错误，请求不合法（400：请求有语法问题、403：拒绝请求、404：客户端所访问的页面不存在）
- 5×× : 服务器端错误，服务器不能处理合法请求（500：服务器内部错误、503：服务不可用）
1.3 Postman基本使用流程
[1] 新建——请求 or 直接点工作区上面Tab页的“+”
[2] 在下拉框选择 HTTP 的 Method 方法并在Text框输入 API 的地址
[3] 在“头”处设置相关请求头信息
[4] 在“主体”处设置相关GET或POST等的参数
[5] 填写好之后，点击 Send 去发送请求 Request
[6] 请求成功之后，底部便可查看Response响应的信息
2. 部署ShowDoc撰写API文档
2.1 ShowDoc与Docker简介
2.1.1 ShowDoc简介
- 是什么：技术人员都很希望别人能写文档，而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版，想着新建的word文档放在哪个目录等各种非技术细节。ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。
- 功能及特点：API文档、数据字典、说明文档、分享与导出、权限管理、编辑功能、多平台、可部署至自己服务器
- 项目地址及官方文档：ShowDoc from Github、ShowDoc官方文档、ShowDoc在线版
ShowDoc功能界面如下：
2.1.2 Docker简介
- 是什么：Docker是一个用于开发，交付和运行应用程序的开放平台。Docker使您能够将应用程序与基础架构分开，从而可以快速交付软件。借助Docker，您可以以与管理应用程序相同的方式来管理基础架构。通过利用Docker的方法来快速交付，测试和部署代码，您可以大大减少编写代码和在生产环境中运行代码之间的延迟。
- 作用：将一整套环境打包封装成镜像，无需重复配置环境，解决环境带来的种种问题。Docker容器间是进程隔离的，谁也不会影响谁。
- 官方文档：Docker官方文档
2.2 安装Docker并部署ShowDoc
2.2.1 在Debian9服务器安装Docker
[1] 设置存储库
Step1：安装sudo命令
|
1 |
$ apt install sudo -y |
Step2：更新apt包索引
|
1 |
$ sudo apt-get update |
Step3：安装包以允许apt通过HTTPS使用存储库
|
1 2 3 4 5 6 |
$ sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg2 \ software-properties-common |
Step4：添加Docker的官方GPG密钥：
|
1 |
$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - |
Step5：验证您现在拥有带指纹的密钥
|
1 |
$ sudo apt-key fingerprint 0EBFCD88 |
Step6： 添加源
|
1 2 3 4 |
$ sudo add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/debian \ $(lsb_release -cs) \ stable" |
[2] 安装DOCKER CE
|
1 2 |
$ sudo apt-get update $ sudo apt-get install docker-ce docker-ce-cli containerd.io |
[3] 验证
Step1：启动docker(如果没有启动)
|
1 |
$ sudo systemctl start docker |
Step2：查看版本
|
1 |
$ sudo docker --version |
[4] 管理Docker
- 为了方便管理Docker及部署在Docker里的项目，可从宝塔面板里下载一个“Docker管理器”。
2.2.2 在Docker环境下部署ShowDoc
我们可以在Docker环境下利用自动脚本来部署ShowDoc
Step1：从官网下载ShowDoc的服务器端showdoc，将其上传到root目录并赋予700权限。
Step2：输入命令安装ShowDoc，成功则如下图所示：
|
1 |
$ ./showdoc # 默认安装中文版。如果想安装英文版，请加上en参数，如 ./showdoc en |
安装好后，showdoc的数据都会存放在 /showdoc_data/html目录下。你可以打开 http://xxx.com:4999 来访问showdoc (xxx.com为你的服务器域名或者IP)。账户密码是showdoc/123456，登录后便可以看到右上方的管理后台，建议修改管理员密码。
附：其他管理showdoc的命令
|
1 2 3 4 |
$ ./showdoc stop #停止 $ ./showdoc restart #重启 $ ./showdoc update #升级showdoc到最新版 $ ./showdoc uninstall #卸载showdoc |
3. 参考资料
[1] Postman 接口测试神器 from Gitbook
[2] api_tool_postman form Github
[4] Postman记录您的API from Postman学习中心
[6] 常见网络错误 from CSDN
