使用Postman测试API并部署ShowDoc撰写文档

2020-09-28 0条评论 170次阅读 1人点赞本文共3283个字，预计阅读时间9分钟。

文章最后修改于：2020-11-16 19:26:10

Contents

1. 使用postman工具测试API
2. 部署ShowDoc撰写API文档
- 2.1 ShowDoc与Docker简介
  - 2.1.1 ShowDoc简介
  - 2.1.2 Docker简介
- 2.2 安装Docker并部署ShowDoc
  - 2.2.1 在Debian9服务器安装Docker
  - 2.2.2 在Docker环境下部署ShowDoc
3. 参考资料

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汉化版的工作界面如下：

《使用Postman测试API并部署ShowDoc撰写文档》

1.1.2 安装postman

Github项目地址：https://github.com/postmanlabs

官网：https://www.postman.com/

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)  从功能上讲，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) 从功能上讲，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：服务不可用）

100 Continue：初始的请求已经接受，客户应当继续发送请求的其余部分。  
101 Switching Protocols：服务器将遵从客户的请求转换到另外一种协议。  

200 OK：一切正常，对GET和POST请求的应答文档跟在后面。
201 Created：服务器已经创建了文档，Location头给出了它的URL 。  
202 Accepted：已经接受请求，但处理尚未完成。  
203 Non-Authoritative Information ：文档已经正常地返回，但一些应答头可能不正确，因为使用的是文档的拷贝。  
204 No Content：没有新文档，浏览器应该继续显示原来的文档。如果用户定期地刷新页面，而 Servlet可以确定用户文档足够新，这个状态代码是很有用的。  
205 Reset Content：没有新的内容，但浏览器应该重置它所显示的内容。用来强制浏览器清除表单输入内容。  
206 Partial Content：客户发送了一个带有 Range 头的 GET 请求，服务器完成了它。  

300 Multiple Choices：客户请求的文档可以在多个位置找到，这些位置已经在返回的文档内列出。如果服务器要提出优先选择，则应该在 Location应答头指明。  
301 Moved Permanently：客户请求的文档在其他地方，新的URL在Location头中给出，浏览器应该自动地访问新的URL 。  
302 Found：类似于301，但新的 URL 应该被视为临时性的替代，而不是永久性的。
303 See Other：类似于 301/302 ，不同之处在于，如果原来的请求是 POST，Location头指定的重定向目标文档应该通过GET提取。 
304 Not Modified ：客户端有缓冲的文档并发出了一个条件性的请求（一般是提供 If-Modified-Since 头表示客户只想比指定日期更新的文档）。服务器告诉客户，原来缓冲的文档还可以继续使用。  
305 Use Proxy：客户请求的文档应该通过 Location 头所指明的代理服务器提取。  
307 Temporary Redirect：和 302相同。许多浏览器会错误地响应 302 应答进行重定向，即使原来的请求是POST，即使它实际上只能在 POST 请求的应答是 303 时才能重定向。由于这个原因，HTTP 1.1新增了307 ，以便更加清楚地区分几个状态代码。

400 Bad Request：请求出现语法错误。  
401 Unauthorized：客户试图未经授权访问受密码保护的页面。应答中会包含一个 WWW-Authenticate 头，浏览器据此显示用户名字/密码对话框，然后在填写合适的 Authorization 头后再次发出请求。  
403 Forbidden：资源不可用。服务器理解客户的请求，但拒绝处理它。通常由于服务器上文件或目录的权限设置导致。  
404 Not Found：无法找到指定位置的资源，这也是一个常用的应答。
405 Method Not Allowed：请求方法（GET、POST、HEAD、DELETE、PUT、TRACE等）对指定的资源不适用。  
406 Not Acceptable：指定的资源已经找到，但它的 MIME 类型和客户在 Accpet 头中所指定的不兼容。  
407 Proxy Authentication Required：类似于 401 ，表示客户必须先经过代理服务器的授权。  
408 Request Timeout：在服务器许可的等待时间内，客户一直没有发出任何请求。客户可以在以后重复同一请求。  
409 Conflict：通常和 PUT 请求有关。由于请求和资源的当前状态相冲突，因此请求不能成功。  
410 Gone：所请求的文档已经不再可用，而且服务器不知道应该重定向到哪一个地址。它和 404 的不同在于，返回 407 表示文档永久地离开了指定的位置，而 404 表示由于未知的原因文档不可用。  
411 Length Required：服务器不能处理请求，除非客户发送一个Content-Length头。  
412 Precondition Failed：请求头中指定的一些前提条件失败。  
413 Request Entity Too Large：目标文档的大小超过服务器当前愿意处理的大小。如果服务器认为自己能够稍后再处理该请求，则应该提供一个 Retry-After头。  
414 Request URI Too Long：URI 太长。  
416 Requested Range Not Satisfiable：服务器不能满足客户在请求中指定的Range头。  

500 Internal Server Error：服务器遇到了意料不到的情况，不能完成客户的请求。  
501 Not Implemented：服务器不支持实现请求所需要的功能。例如，客户发出了一个服务器不支持的 PUT 请求。  
502 Bad Gateway：服务器作为网关或者代理时，为了完成请求访问下一个服务器，但该服务器返回了非法的应答。  
503 Service Unavailable：服务器由于维护或者负载过重未能应答。例如，Servlet可能在数据库连接池已满的情况下返回503。服务器返回 503时可以提供一个 Retry-After头。  
504 Gateway Timeout：由作为代理或网关的服务器使用，表示不能及时地从远程服务器获得应答。  
505 HTTP Version Not Supported：服务器不支持请求中所指明的 HTTP 版本。

100 Continue：初始的请求已经接受，客户应当继续发送请求的其余部分。

101 Switching Protocols：服务器将遵从客户的请求转换到另外一种协议。

200 OK：一切正常，对GET和POST请求的应答文档跟在后面。

201 Created：服务器已经创建了文档，Location头给出了它的URL 。

202 Accepted：已经接受请求，但处理尚未完成。

203 Non-Authoritative Information ：文档已经正常地返回，但一些应答头可能不正确，因为使用的是文档的拷贝。

204 No Content：没有新文档，浏览器应该继续显示原来的文档。如果用户定期地刷新页面，而 Servlet可以确定用户文档足够新，这个状态代码是很有用的。

205 Reset Content：没有新的内容，但浏览器应该重置它所显示的内容。用来强制浏览器清除表单输入内容。

206 Partial Content：客户发送了一个带有 Range 头的 GET 请求，服务器完成了它。

300 Multiple Choices：客户请求的文档可以在多个位置找到，这些位置已经在返回的文档内列出。如果服务器要提出优先选择，则应该在 Location应答头指明。

301 Moved Permanently：客户请求的文档在其他地方，新的URL在Location头中给出，浏览器应该自动地访问新的URL 。

302 Found：类似于301，但新的 URL 应该被视为临时性的替代，而不是永久性的。

303 See Other：类似于 301/302 ，不同之处在于，如果原来的请求是 POST，Location头指定的重定向目标文档应该通过GET提取。

304 Not Modified ：客户端有缓冲的文档并发出了一个条件性的请求（一般是提供 If-Modified-Since 头表示客户只想比指定日期更新的文档）。服务器告诉客户，原来缓冲的文档还可以继续使用。

305 Use Proxy：客户请求的文档应该通过 Location 头所指明的代理服务器提取。

307 Temporary Redirect：和 302相同。许多浏览器会错误地响应 302 应答进行重定向，即使原来的请求是POST，即使它实际上只能在 POST 请求的应答是 303 时才能重定向。由于这个原因，HTTP 1.1新增了307 ，以便更加清楚地区分几个状态代码。

400 Bad Request：请求出现语法错误。

401 Unauthorized：客户试图未经授权访问受密码保护的页面。应答中会包含一个 WWW-Authenticate 头，浏览器据此显示用户名字/密码对话框，然后在填写合适的 Authorization 头后再次发出请求。

403 Forbidden：资源不可用。服务器理解客户的请求，但拒绝处理它。通常由于服务器上文件或目录的权限设置导致。

404 Not Found：无法找到指定位置的资源，这也是一个常用的应答。

405 Method Not Allowed：请求方法（GET、POST、HEAD、DELETE、PUT、TRACE等）对指定的资源不适用。

406 Not Acceptable：指定的资源已经找到，但它的 MIME 类型和客户在 Accpet 头中所指定的不兼容。

407 Proxy Authentication Required：类似于 401 ，表示客户必须先经过代理服务器的授权。

408 Request Timeout：在服务器许可的等待时间内，客户一直没有发出任何请求。客户可以在以后重复同一请求。

409 Conflict：通常和 PUT 请求有关。由于请求和资源的当前状态相冲突，因此请求不能成功。

410 Gone：所请求的文档已经不再可用，而且服务器不知道应该重定向到哪一个地址。它和 404 的不同在于，返回 407 表示文档永久地离开了指定的位置，而 404 表示由于未知的原因文档不可用。

411 Length Required：服务器不能处理请求，除非客户发送一个Content-Length头。

412 Precondition Failed：请求头中指定的一些前提条件失败。

413 Request Entity Too Large：目标文档的大小超过服务器当前愿意处理的大小。如果服务器认为自己能够稍后再处理该请求，则应该提供一个 Retry-After头。

414 Request URI Too Long：URI 太长。

416 Requested Range Not Satisfiable：服务器不能满足客户在请求中指定的Range头。

500 Internal Server Error：服务器遇到了意料不到的情况，不能完成客户的请求。

501 Not Implemented：服务器不支持实现请求所需要的功能。例如，客户发出了一个服务器不支持的 PUT 请求。

502 Bad Gateway：服务器作为网关或者代理时，为了完成请求访问下一个服务器，但该服务器返回了非法的应答。

503 Service Unavailable：服务器由于维护或者负载过重未能应答。例如，Servlet可能在数据库连接池已满的情况下返回503。服务器返回 503时可以提供一个 Retry-After头。

504 Gateway Timeout：由作为代理或网关的服务器使用，表示不能及时地从远程服务器获得应答。

505 HTTP Version Not Supported：服务器不支持请求中所指明的 HTTP 版本。

1.3 Postman基本使用流程

[1] 新建——请求 or 直接点工作区上面Tab页的“+”

[2] 在下拉框选择 HTTP 的 Method 方法并在Text框输入 API 的地址

[3] 在“头”处设置相关请求头信息

[4] 在“主体”处设置相关GET或POST等的参数

[5] 填写好之后，点击 Send 去发送请求 Request

[6] 请求成功之后，底部便可查看Response响应的信息

《使用Postman测试API并部署ShowDoc撰写文档》

2. 部署ShowDoc撰写API文档

2.1 ShowDoc与Docker简介

2.1.1 ShowDoc简介

是什么：技术人员都很希望别人能写文档，而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版，想着新建的word文档放在哪个目录等各种非技术细节。ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。
功能及特点：API文档、数据字典、说明文档、分享与导出、权限管理、编辑功能、多平台、可部署至自己服务器
项目地址及官方文档：ShowDoc from Github、ShowDoc官方文档、ShowDoc在线版

ShowDoc功能界面如下：

《使用Postman测试API并部署ShowDoc撰写文档》

2.1.2 Docker简介

是什么：Docker是一个用于开发，交付和运行应用程序的开放平台。Docker使您能够将应用程序与基础架构分开，从而可以快速交付软件。借助Docker，您可以以与管理应用程序相同的方式来管理基础架构。通过利用Docker的方法来快速交付，测试和部署代码，您可以大大减少编写代码和在生产环境中运行代码之间的延迟。
作用：将一整套环境打包封装成镜像，无需重复配置环境，解决环境带来的种种问题。Docker容器间是进程隔离的，谁也不会影响谁。
官方文档：Docker官方文档

2.2 安装Docker并部署ShowDoc

2.2.1 在Debian9服务器安装Docker

[1] 设置存储库

Step1：安装sudo命令

$ apt install sudo -y

1	$ apt install sudo -y

Step2：更新apt包索引

$ sudo apt-get update

1	$ sudo apt-get update

Step3：安装包以允许apt通过HTTPS使用存储库

$ sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg2 \
    software-properties-common

$ sudo apt-get install \

apt-transport-https \

ca-certificates \

curl \

gnupg2 \

software-properties-common

Step4：添加Docker的官方GPG密钥：

$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

1	$ curl -fsSL https://download.docker.com/linux/debian/gpg \| sudo apt-key add -

Step5：验证您现在拥有带指纹的密钥

$ sudo apt-key fingerprint 0EBFCD88

1	$ sudo apt-key fingerprint 0EBFCD88

Step6：添加源

$ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/debian \
   $(lsb_release -cs) \
   stable"

$ sudo add-apt-repository \

"deb [arch=amd64] https://download.docker.com/linux/debian \

$(lsb_release -cs) \

stable"

[2] 安装DOCKER CE

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io

1 2	$ sudo apt-get update $ sudo apt-get install docker-ce docker-ce-cli containerd.io

[3] 验证

Step1：启动docker(如果没有启动)

$ sudo systemctl start docker

1	$ sudo systemctl start docker

Step2：查看版本

$ sudo docker --version

1	$ sudo docker --version

[4] 管理Docker

为了方便管理Docker及部署在Docker里的项目，可从宝塔面板里下载一个“Docker管理器”。

2.2.2 在Docker环境下部署ShowDoc

我们可以在Docker环境下利用自动脚本来部署ShowDoc

Step1：从官网下载ShowDoc的服务器端showdoc，将其上传到root目录并赋予700权限。

Step2：输入命令安装ShowDoc，成功则如下图所示：

$ ./showdoc   # 默认安装中文版。如果想安装英文版，请加上en参数，如 ./showdoc en

1	$ ./showdoc # 默认安装中文版。如果想安装英文版，请加上en参数，如 ./showdoc en

《使用Postman测试API并部署ShowDoc撰写文档》

安装好后，showdoc的数据都会存放在 /showdoc_data/html目录下。你可以打开 http://xxx.com:4999 来访问showdoc (xxx.com为你的服务器域名或者IP)。账户密码是showdoc/123456，登录后便可以看到右上方的管理后台，建议修改管理员密码。

附：其他管理showdoc的命令

$ ./showdoc stop          #停止
$ ./showdoc restart       #重启
$ ./showdoc update        #升级showdoc到最新版
$ ./showdoc uninstall     #卸载showdoc

$ ./showdoc stop #停止

$ ./showdoc restart #重启

$ ./showdoc update #升级showdoc到最新版

$ ./showdoc uninstall #卸载showdoc

3. 参考资料

[1] Postman 接口测试神器 from Gitbook

[2] api_tool_postman form Github

[3] Postman汉化版 from GitHub

[4] Postman记录您的API from Postman学习中心

[5] 快速掌握Postman实现接口测试 from 知乎

[6] 常见网络错误 from CSDN

[7] Debian安装Docker_from 简书

[8] ShowDoc自动脚本安装 from showdoc官方文档

BlackCatの小窝

Mortal's Blog

使用Postman测试API并部署ShowDoc撰写文档

1. 使用postman工具测试API

1.1 postman简介

1.1.1 postman是什么

1.1.2 安装postman

1.2 基础知识储备

1.2.1 Web API简介及示例接口

1.2.2 Get与Post的区别

1.2.3 常见网络状态码及含义

1.3 Postman基本使用流程

2. 部署ShowDoc撰写API文档

2.1 ShowDoc与Docker简介

2.1.1 ShowDoc简介

2.1.2 Docker简介

2.2 安装Docker并部署ShowDoc

2.2.1 在Debian9服务器安装Docker

2.2.2 在Docker环境下部署ShowDoc

3. 参考资料

本作品采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可

发表评论取消回复

历史记录 [ 注意：部分数据仅限于当前浏览器 ]清空

Mortal's Blog

1. 使用postman工具测试API

1.1 postman简介

1.1.1 postman是什么

1.1.2 安装postman

1.2 基础知识储备

1.2.1 Web API简介及示例接口

1.2.2 Get与Post的区别

1.2.3 常见网络状态码及含义

1.3 Postman基本使用流程

2. 部署ShowDoc撰写API文档

2.1 ShowDoc与Docker简介

2.1.1 ShowDoc简介

2.1.2 Docker简介

2.2 安装Docker并部署ShowDoc

2.2.1 在Debian9服务器安装Docker

2.2.2 在Docker环境下部署ShowDoc

3. 参考资料

本作品采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可

发表评论 取消回复

历史记录 [ 注意：部分数据仅限于当前浏览器 ]清空

本作品采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可

发表评论取消回复