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

  1. 1. 使用postman工具测试API
    1. 1.1 postman简介
      1. 1.1.1 postman是什么
      2. 1.1.2 安装postman
    2. 1.2 基础知识储备
      1. 1.2.1 Web API简介及示例接口
      2. 1.2.2 Get与Post的区别
      3. 1.2.3 常见网络状态码及含义
    3. 1.3 Postman基本使用流程
  2. 2. 部署ShowDoc撰写API文档
    1. 2.1 ShowDoc简介
    2. 2.2 安装Docker环境
    3. 2.3 使用脚本部署ShowDoc服务
    4. 2.4 新建网站设置反向代理
    5. 2.5 申请泛域名证书并开启HTTPS
      1. 2.5.1 安装 acme.sh
      2. 2.5.2 生成SSL泛域名证书
      3. 2.5.3 给网站开启HTTPS
  3. 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汉化版的工作界面如下:

1.1.2 安装postman

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

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

Postman 可以单独作为一个应用安装,也可以作为 Chrome 的一个插件安装,建议选择前者。

如果你英文不好,可选择汉化版下载: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.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简介

是什么:技术人员都很希望别人能写文档,而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版,想着新建的word文档放在哪个目录等各种非技术细节。ShowDoc就是一个非常适合IT团队的在线文档分享工具,它可以加快团队之间沟通的效率。

功能及特点:API文档、数据字典、说明文档、分享与导出、权限管理、编辑功能、多平台、可部署至自己服务器

项目地址及官方文档:ShowDoc from GithubShowDoc官方文档ShowDoc在线版

ShowDoc功能界面如下:

2.2 安装Docker环境

我们可以在Docker下利用自动脚本来部署ShowDoc,因此我们需要先安装Docker环境。VPS系统用的是Debian 10 x86_64。Docker的基本概念及使用这里就不赘述了,如果不会的话见我的另一篇博客:VPS基本部署环境的搭建与配置

1
2
3
4
$ apt-get update -y && apt-get install curl -y  # 安装curl
$ curl https://get.docker.com | sh - # 安装docker
$ sudo systemctl start docker # 启动docker服务
$ docker version # 查看docker版本(客户端要与服务端一致)

2.3 使用脚本部署ShowDoc服务

Step1:从官网下载ShowDoc的服务器端部署脚本 showdoc,将其上传到root目录并赋予700权限。

注:我们可以根据自己的需要对该一键部署脚本进行自定义修改,也可提取有效命令自行手动安装。后续的使用及配置以原始脚本为例。

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

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

安装好后,showdoc的数据都会存放在 /showdoc_data/html目录下。

此时你可以打开 http://IP:4999 来访问showdoc,后续我们将配置反向代理用指定域名访问并开启HTTPS(不配置也能用)

账户密码是showdoc/123456,登录后便可以看到右上方的管理后台,建议修改管理员密码。

附:其他管理showdoc的命令

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

设置开机自启:

1
$ docker update showdoc --restart=always

2.4 新建网站设置反向代理

Step1:新建网站

宝塔面板——网站——添加站点——填写域名即可(其他的都不需要,我们只是用它来做反向代理和配置HTPPS)

Step2:开启反向代理

宝塔面板——网站——设置——反向代理——添加反向代理——填写代理名称和目标URL

showDoc开启反向代理

2.5 申请泛域名证书并开启HTTPS

SSL证书是一种数字证书,用于加密从用户的浏览器发送到Web服务器的数据。 通过这种方式,发送的数据对于使用Wireshark等数据包嗅探器来拦截和窃听您的通信的黑客来说是安全的。

Chrome一直在推动https,所有的http协议网站被标记为不安全,如果再不对网站进行https改造的话,那么可能会对信任度造成一定的影响,所以说对一个面向用户的网站来说,开启https是非常有必要的。

下面将使用acme.sh开源项目申请免费的 Let’s Encrypt 泛域名SSL证书。

注:如果懒得折腾泛域名证书,也可在宝塔面板直接傻瓜式申请Let’s Encrypt的单域名SSL证书(宝塔面板——网站——设置——SSL——Let’s Encrypt——勾选域名,点文件验证——申请出来后设置强制HTTPS)。

2.5.1 安装 acme.sh

1
$ curl  https://get.acme.sh | sh

acme.sh

普通用户和 root 用户都可以安装使用,安装过程进行了以下几步:

  • [1] 把 acme.sh 安装到你的 root 目录下,并创建 一个 bash 的 alias, 方便你的使用。

  • [2] 自动为你创建 cronjob, 每天 0:00 点自动检测所有的证书, 如果快过期了, 需要更新, 则会自动更新证书。

注:安装过程不会污染已有的系统任何功能和文件,所有的修改都限制在安装目录中。那个socat未安装的问题不用管,那是http验证无Web Server时才需要的。

2.5.2 生成SSL泛域名证书

acme.sh 实现了 acme 协议支持的所有验证协议,一般有两种方式验证:http 和 dns 验证。

  • http 验证:http 方式需要在你的网站根目录下放置一个文件,来验证你的域名所有权。
  • dns 验证:dns 方式,在域名上添加一条 txt 解析记录,验证域名所有权。

dns 方式的可以使用域名解析商提供的 API 自动添加 txt 记录完成验证,下面我们将采用这种方法申请Namesilo的泛域名证书。

Step1:打开 https://www.namesilo.com/account/api-manager 去申请 NameSilo API,勾选第2个复选框,点击Generate,即可生成。

申请NameSilo API

注:务必不要勾选上Generate key for read-only access的哪个复选框,否则会导致Unable to add the DNS record. Error add txt for domain的问题。另外,生成的API只出现一次,如果没记下来只能重置。

Step2:在服务器输入以下命令,实现自动dns验证生成泛域名证书。

1
2
3
$ cd /root/.acme.sh
$ export Namesilo_Key="xxxxxxxxxxxxxxxxxxxxxxxx"
$ ./acme.sh --issue --dns dns_namesilo --dnssleep 1800 -d example.com -d *.example.com

等待1800s即可看到申请下来的SSL证书(NameSilo的验证比较慢,官方文档上写的900s有时不足以验证完)

申请下来的SSL证书

生成文件都放在/root/.acme.sh/example.com/目录下,其中:example.com.key是密钥文件,fullchain.cer是证书文件。

注:如果你的域名不是NameSilo的,上述操作有所不同,具体请参考: https://github.com/acmesh-official/acme.sh/wiki/dnsapi

2.5.3 给网站开启HTTPS

打开宝塔面板——网站——设置——SSL——其他证书,把example.com.key密钥文件、fullchain.cer证书文件复制上去,强制https。

开启HTTPS

上述配置完成后,showDoc的访问URL为:https://域名

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官方文档