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