Mortal's Blog

生命不息,折腾不止!

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

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

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://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 常见网络状态码及含义

常见网络状态码及其含义的详细说明:

  • 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响应的信息

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

2. 部署ShowDoc撰写API文档

2.1 ShowDoc与Docker简介

2.1.1 ShowDoc简介

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

Step2:更新apt包索引

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

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

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

Step6: 添加源

[2] 安装DOCKER CE

[3] 验证

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

Step2:查看版本

[4] 管理Docker

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

2.2.2 在Docker环境下部署ShowDoc

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

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

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

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

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

附:其他管理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官方文档

点赞

发表评论

电子邮件地址不会被公开。

EA PLAYER &

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

      00:00/00:00