API文档管理平台

绝地灬酷狼 2022-02-02 08:25 586阅读 0赞

# [API文档管理平台][API] #

# 一、应用场景 #

在公司中，有很多开发，每个人维护的api接口是不一样的。如果有一个统一的api文档管理平台，每个开发，把自己维护的接口录入进去。

之后再开发别的功能时，不需要重复造轮子，直接调用就可以了。有新员工入职时，也可以快速上手！

关于api文档管理，网上有很多。有在线收费的，也有开源的。基于节省成本考虑，这里主要介绍2个开源工具：ShowDoc和YApi。

下面会详细介绍着2个工具的使用方法，都是基于docker安装的！

# 二、ShowDoc #

ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具。你可以使用Showdoc来编写在线API文档、技术文档、数据字典、在线手册。

官方地址：

[https://www.showdoc.cc/][https_www.showdoc.cc]

## 基于docker安装 ##

本文所使用的系统是  ubuntu-16.04.5-server-amd64，先安装docker

apt-get install -y docker.io
    apt-get clean all

下载国内镜像

docker pull registry.docker-cn.com/star7th/showdoc

新建存放showdoc数据的目录

mkdir /showdoc_data
    mkdir /showdoc_data/html
    chmod 777 -R /showdoc_data

启动showdoc容器。启动完了后别忘记后面还有转移数据的步骤。

docker run -d --name showdoc -p 4999:80 -v /showdoc_data/html:/var/www/html/ registry.docker-cn.com/star7th/showdoc

转移数据

docker exec showdoc \cp -fr /showdoc_data/html/ /var/www/

设置权限

chmod 777 -R /showdoc_data

根据以上命令操作的话，往后showdoc的数据都会存放在 /showdoc\_data/html 目录下。  
你可以打开  http://localhost:4999 来访问showdoc。账户密码是showdoc/123456

访问页面

http://192.168.91.128:4999

效果如下：

![1341090-20181121095752436-225538492.png][]

点击进入首页

![1341090-20181121095814402-272369116.png][]

点击右侧的登录，输入用户名和密码

![1341090-20181121095911204-417661569.png][]

登录之后，点击新建项目

![1341090-20181121095930313-592122563.png][]

输入项目名和描述，点击提交

![1341090-20181121100019460-2140498367.png][]

项目就创建好了，点击项目

![1341090-20181121100045313-554847579.png][]

点击左侧的添加按钮

![1341090-20181121100110489-1006111511.png][]

点击插入API接口模板，点击右侧的保存

可以看出，左边就是markdown格式，右边就是预览效果

![1341090-20181121100200385-489646492.png][]

保存之后，点击返回，效果如下：

![1341090-20181121100311276-850200504.png][]

ok，到这里，一个api文档就完成了。关于showdoc其他操作，请参考链接：

[https://www.showdoc.cc/help?page\_id=65610][https_www.showdoc.cc_help_page_id_65610]

是不是很Nice！那么问题来了，开发要测试这个接口怎么办？

打开postman，输入上面的请求url，选择POST请求，输入参数.....

是不是很麻烦？还得让开发安装postman，进行一系列操作。

那么有没有直接在这个网页上，集成postman功能，可以直接发送POST请求，查看返回结果呢？

有，那就是YApi。

# 三、YApi(推荐) #

## 介绍 ##

**Yapi** 由 YMFE 开源，旨在为开发、产品、测试人员提供更优雅的接口管理服务，可以帮助开发者轻松创建、发布、维护 API。

*  **权限管理**  
    YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求
 *  **可视化接口管理**  
    基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率
 *  **Mock Server**  
    易用的 Mock Server，再也不用担心 mock 数据的生成了
 *  **自动化测试**  
    完善的接口自动化测试,保证数据的正确性
 *  **数据导入**  
    支持导入 swagger, postman, har 数据格式，方便迁移旧项目
 *  **插件机制**  
    强大的插件机制，满足各类业务需求

官方地址：

[https://yapi.ymfe.org/][https_yapi.ymfe.org]

## 使用 Docker 构建 Yapi ##

### 1、创建 MongoDB 数据卷 ###

docker volume create mongo_data_yapi

### 2、启动 MongoDB ###

docker run -d --name mongo-yapi -v mongo_data_yapi:/data/db mongo

### 3、获取 Yapi 镜像 ###

版本信息可在 [阿里云镜像仓库][Link 1] 查看

docker pull registry.cn-hangzhou.aliyuncs.com/anoy/yapi

### 4、初始化 Yapi ###

初始化数据库索引及管理员账号

docker run -it --rm \
      --link mongo-yapi:mongo \
      --entrypoint npm \
      --workdir /api/vendors \
      registry.cn-hangzhou.aliyuncs.com/anoy/yapi \
      run install-server

自定义配置文件挂载到目录 `/api/config.json`，官方自定义配置文件 -> [传送门][Link 2]

### 5、启动 Yapi 服务 ###

docker run -d \
      --name yapi \
      --link mongo-yapi:mongo \
      --workdir /api/vendors \
      -p 3000:3000 \
      registry.cn-hangzhou.aliyuncs.com/anoy/yapi \
      server/app.js

## 使用 Yapi ##

访问 http://localhost:3000 登录账号 admin@admin.com，密码 ymfe.org

点击登录

![1341090-20181121101927676-1719897834.png][]

输入用户名和密码

![1341090-20181121102006594-848053516.png][]

点击添加项目

![1341090-20181121102116110-2084476127.png][]

创建项目

![1341090-20181121102506169-793686063.png][]

点击添加接口

![1341090-20181121102316578-1277856602.png][]

输入接口名称和接口路径

![1341090-20181121102610767-572112824.png][]

接口就创建好了，点击编辑，添加参数

![1341090-20181121102659164-1310031033.png][]

添加2个参数

![1341090-20181121112929151-2108882552.png][]

设置返回数据，点击导入json

![1341090-20181121102925312-1974612928.png][]

输入json

![1341090-20181121104618471-651487271.png][]

勾选，表示必须返回。输入备注

![1341090-20181121103737946-1816015517.png][]

点击下面的保存，点击预览，效果如下：

![1341090-20181121113030572-9694789.png][]

点击运行，需要安装插件

![1341090-20181121104023378-162652962.png][]

对于最新版的谷歌浏览器，比如版本为70.0.3538.67，它是不允许本地安装的，只能在谷歌商店安装！

点击google商店获取，跳转页面

![1341090-20181121104157098-2041430365.png][]

点击右侧的添加，点击添加扩展程序

![1341090-20181121104220155-380887924.png][]

添加完成之后，再次刷新页面，点击运行，效果如下：

![1341090-20181121113058248-899355530.png][]

这上面，就可以输入一些值了。在下面的Response，就会返回结果

![1341090-20181121104416281-1847276633.png][]

如果要测试的地址和当前url不匹配，可以手动设置

点击环境设置

![1341090-20181121112749303-1719510622.png][]

输入测试服务器的ip和端口号

![1341090-20181121112706984-1312258013.png][]

发送POST请求，输入参数

![1341090-20181121113610439-620747595.png][]

返回正确时，效果如下：

![1341090-20181121112629805-683175675.png][]

最后将状态，选择为已完成

![1341090-20181121104821408-378510868.png][]

刷新页面，查看预览，效果如下：

![1341090-20181121104906880-751674280.png][]

## Chrome浏览器离线安装插件 ##

在这个页面中，点击手动下载

![1341090-20181121104023378-162652962.png][]

它会下载一个crossRequest.zip文件，将这个文件解压，会得到一个2.8\_0.crx

![1341090-20181122155206128-68717189.png][]

将2.8\_0.crx的后缀crx改成rar

![1341090-20181122155312231-1132466705.png][]

将这个文件解压

![1341090-20181122155333357-1792804039.png][]

打开 Chrome浏览器，点击更多工具-->扩展程序

![1341090-20181122160115995-1392392291.gif][]

默认的开发者模式是关闭的

![1341090-20181122155453468-235986252.png][]

将它开启，会出现一个加载已解压的扩展程序

![1341090-20181122155523513-1773332636.png][]

点击它，选择刚刚解压的文件夹

![1341090-20181122155600191-1660122131.png][]

扩展程序就安装好了！

![1341090-20181122155623315-1347928539.png][]

## 基于DRF的测试接口 ##

假设没有测试接口，可以使用Python的rest framework模块来模拟一个登陆接口。

确保已经安装了以下2个模块

pip3 install Django
    pip3 install djangorestframework

新建项目untitled

![1341090-20181121114444712-977399815.png][]

修改settings.py，注册djangorestframework，最后一行添加

INSTALLED_APPS = [
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
        'app.apps.AppConfig',
        'rest_framework',
    ]

继续修改settings.py，允许监听所有Ip

ALLOWED_HOSTS = ['*']

修改views.py，增加视图函数

from django.shortcuts import render
    from rest_framework.views import APIView
    
    from rest_framework.response import Response
    
    class LoginView(APIView):
        def post(self, request, *args, **kwargs):
            data = {
          "code": "200", "data": "ok", "error": ""}
            return Response(data)

修改urls.py，增加路由

from django.contrib import admin
    from django.urls import path,re_path
    from app01 import views
    
    urlpatterns = [
        path('admin/', admin.site.urls),
        re_path(r'^(?P<version>[v1|v2]+)/login', views.LoginView.as_view(), name='login'),
    ]

修改启动参数

![1341090-20181121114809214-798932040.png][]

监听0.0.0.0

![1341090-20181121114824848-86827752.png][]

启动Django，使用postman测试接口

![1341090-20181121114913435-210645888.png][]

本文参考链接：

[https://www.jianshu.com/p/a97d2efb23c5 ][https_www.jianshu.com_p_a97d2efb23c5]

posted @ 2018-11-19 10:45 [肖祥][Link 3] 阅读( ...) 评论( ...) [编辑][Link 4] 收藏

[API]: https://www.cnblogs.com/xiao987334176/p/9993612.html
[https_www.showdoc.cc]: https://www.showdoc.cc/
[1341090-20181121095752436-225538492.png]: /images/20220202/21b7c2e2fd874b579a2d5ddc62a3a91d.png
[1341090-20181121095814402-272369116.png]: /images/20220202/24e8817f92214aa1a11869b9f56e93b1.png
[1341090-20181121095911204-417661569.png]: /images/20220202/1d33be6ad66543fd996cdb175bbcd668.png
[1341090-20181121095930313-592122563.png]: /images/20220202/2d0d6aceccb14b96b80e5ea55384d381.png
[1341090-20181121100019460-2140498367.png]: /images/20220202/a1a905b140734c96a71d7538ac015e32.png
[1341090-20181121100045313-554847579.png]: /images/20220202/0f7c7de6ed394393b35403562c2df205.png
[1341090-20181121100110489-1006111511.png]: /images/20220202/7ede3ea2bc3f42758e772553618d8363.png
[1341090-20181121100200385-489646492.png]: /images/20220202/64cd6a330e2f4323b6a28993c414efe7.png
[1341090-20181121100311276-850200504.png]: /images/20220202/f26edffb3ee041db994b3529bd45b567.png
[https_www.showdoc.cc_help_page_id_65610]: https://www.showdoc.cc/help?page_id=65610
[https_yapi.ymfe.org]: https://yapi.ymfe.org/
[Link 1]: https://dev.aliyun.com/detail.html?spm=5176.1972343.2.26.I97LV8&repoId=139034
[Link 2]: https://github.com/YMFE/yapi/blob/master/config_example.json
[1341090-20181121101927676-1719897834.png]: /images/20220202/108f0dbaa59d40d890eb5d725f389030.png
[1341090-20181121102006594-848053516.png]: /images/20220202/dd8a69a6b62541dd805c20e7a16efce6.png
[1341090-20181121102116110-2084476127.png]: /images/20220202/aafcba267214465a907024716139e2bd.png
[1341090-20181121102506169-793686063.png]: /images/20220202/12b1a7afa5224fd4944ae72bc8de7e73.png
[1341090-20181121102316578-1277856602.png]: /images/20220202/5cc32732e9f64560ab77c86ef941669d.png
[1341090-20181121102610767-572112824.png]: /images/20220202/a9d96703d95543f7a829b733a2ed300a.png
[1341090-20181121102659164-1310031033.png]: /images/20220202/1598b653438b4a7ba301732251672f4f.png
[1341090-20181121112929151-2108882552.png]: /images/20220202/360abfbc70964793b8f722bc29b415d3.png
[1341090-20181121102925312-1974612928.png]: /images/20220202/53c3352d79044eaaa854d82a17cfc7ae.png
[1341090-20181121104618471-651487271.png]: /images/20220202/748883667c264289b3922b496df4ab81.png
[1341090-20181121103737946-1816015517.png]: /images/20220202/0b4c5b629ea24888b42c47a7dbe28a0d.png
[1341090-20181121113030572-9694789.png]: /images/20220202/eaec7d1d248b45078a693d5c77f22826.png
[1341090-20181121104023378-162652962.png]: /images/20220202/cb86a3e57f6f4464bb4fb6f90dbb17f5.png
[1341090-20181121104157098-2041430365.png]: /images/20220202/dca507140e7742d18f13db3c8f7ddc6b.png
[1341090-20181121104220155-380887924.png]: /images/20220202/66dbb6f2eaf4404fbac6b9e1a9a519e9.png
[1341090-20181121113058248-899355530.png]: /images/20220202/dc072e98bdc64d0895d024c5154cf6a4.png
[1341090-20181121104416281-1847276633.png]: /images/20220202/bc69992e1e41484580edd5c03490f6f9.png
[1341090-20181121112749303-1719510622.png]: /images/20220202/5066982e0df54d7f86717376f6f5f194.png
[1341090-20181121112706984-1312258013.png]: /images/20220202/11d28a4ede6047b0baea2787b6b0bdf5.png
[1341090-20181121113610439-620747595.png]: /images/20220202/17ddc556c675421788b347ad28e4aa88.png
[1341090-20181121112629805-683175675.png]: /images/20220202/8a0fb7dba199473eaf4a43f8cfb515dd.png
[1341090-20181121104821408-378510868.png]: /images/20220202/e6390586c4c84acd84ca9f4ae348c03e.png
[1341090-20181121104906880-751674280.png]: /images/20220202/87601396c6ea481d810323ea364988e7.png
[1341090-20181122155206128-68717189.png]: /images/20220202/2c4d03a7df27413dba6a8ab977c3ba99.png
[1341090-20181122155312231-1132466705.png]: /images/20220202/1549888a779f4df785c6d371bd1d39b3.png
[1341090-20181122155333357-1792804039.png]: /images/20220202/cec1ac9d58324235a658358b3f160bff.png
[1341090-20181122160115995-1392392291.gif]: /images/20220202/1dd429d71bfc42238700194faa9a395d.png
[1341090-20181122155453468-235986252.png]: /images/20220202/73995a96ab4c4c1ba4a80b38310fa334.png
[1341090-20181122155523513-1773332636.png]: /images/20220202/a34bedc329334a8684d927258c864862.png
[1341090-20181122155600191-1660122131.png]: /images/20220202/375eedd340b140339e91219c861ebfbd.png
[1341090-20181122155623315-1347928539.png]: /images/20220202/db635a7ddd6947079cbe18b51134451c.png
[1341090-20181121114444712-977399815.png]: /images/20220202/196c1ecb90ff41d58a41ebfcceb02535.png
[1341090-20181121114809214-798932040.png]: /images/20220202/7bd8363b2df243a4bb9f5ba5298e25e2.png
[1341090-20181121114824848-86827752.png]: /images/20220202/5a930eba082d43c6ba60aec6f050f533.png
[1341090-20181121114913435-210645888.png]: /images/20220202/98733146399c4d78926b80d9f118bb63.png
[https_www.jianshu.com_p_a97d2efb23c5]: https://www.jianshu.com/p/a97d2efb23c5%20
[Link 3]: https://www.cnblogs.com/xiao987334176/
[Link 4]: https://i.cnblogs.com/EditPosts.aspx?postid=9993612