一、背景

我正在建设一个租房平台，进行基于租房业务的架构实践。我尝试着按照不同领域创建了几个微服务，写了一些接口，准备模拟真正的IT企业开发环境，但是接口多了难免有变更，维护成本，目前一个人的话维护接口文档确实很费时间，无法投入到更多架构，服务设计落地上。因此需要有一个文档管理平台，来管理不同微服务的接口描述，便于后面多人开发的时候提供基础文档。

二、文档管理选型

2.1 方案1-自研

当时遇到接口文档管理瓶颈之后，想着可以借用之前自己捣鼓的文档管理工具代码进行继续开发和迭代，但是也无异于从头搞一套文档管理工具，因此自研的成本也比较高，为了快速辅助业务开发，自研的道路行不通。

2.2 寻找开源免费产品

在调研的时候也发现市面上开源的接口文档管理工具有很多，因此更加坚定了使用开源产品的念头，在寻找开源平台的时候也做了一些评估，比如轻量级，可二次开发，可以快熟上手，与业务工程松耦合，不侵入业务代码等等。经过一些调研发现有很多不错的产品比如smartdoc,yapi,swagger,而且都有大规模使用。综合评估下决定还是使用yapi吧，简单来说逃脱不了真香定律，但是yapi的文档管理适合企业级开发应用，同时适合多团队项目使用，便于接口管理，另外也调研了基于yapi的一些工具生态，集成插件等，这些做的都比较好。因此，yapi便是我首要调研落地使用的开源产品。

三、windows部署Yapi

要想使用yapi并不是没有成本的，在部署之前我们需要了解一下yapi的依赖环境，首先需要安装node.js，另外yapi的文档管理基于mongodb，因此这里也需要先安装mongodb。在跟其他文档管理工具比较的时候yapi的一个明显的缺点就是比较重，需要更多的基础设施。

3.1 windows 安装mongodb

在启动yapi之前，这里需要先安装mongodb.先下载安装包，我本地的安装包是：mongodb-win32-x86_64-2008plus-ssl-3.4.10-signed.msi。

下载安装参考这个博客：https://www.cnblogs.com/zhuziyu/p/9213891.html。下图是我的安装目录：

在install里面新建目录etc,E:\programfiles\softtools\mongodb\install\etc

新建配置文件mongodb.conf，内容如下：

dbpath=E:\programfiles\softtools\mongodb\install\data #数据库路径
logpath=E:\programfiles\softtools\mongodb\install\logs\mongodb.log #日志输出文件路径
logappend=true #错误日志采用追加模式，配置这个选项后mongodb的日志会追加到现有的日志文件，而不是重新创建一个新文件
journal=true #启用日志文件，默认启用

cmd进入install文件夹下的bin目录，执行命令：

mongod --config E:\programfiles\softtools\mongodb\install\etc\mongodb.conf

上述命令是启动mongodb服务的命令，安装博客链接中的mongo命令，类似于客户端访问，这里要区分开。执行命令之后访问http://localhost:27017，判断是否启动成功。

3.2 windows 安装Yapi并启动

安装之前这里给出yapi的官方文档链接：https://hellosean1025.github.io/yapi/documents/index.html

参考内网部署链接：https://hellosean1025.github.io/yapi/devops/index.html

基于windows平台的话，其实也很简单，参考上面文档中的命令行部署即可。

3.3 配置easyapi-idea插件

经过一番调研之后，发现yapi的一些集成插件还是挺多的，这里给出我认为比较好的一款插件，easyapi-idea插件。官网链接：http://easyyapi.com/documents/index.html

安装方式跟其他idea插件类似,,这里参考官方文档即可。

3.4 导出文档实战

进入vendor目录，启动yapi服务器，如下图：

 

进行项目配置，yapi需要配置用户名，密码，由于启动依赖mongodb,因此需要先启动mongodb。配置完成第二次启动则可以通过下面的命令启动yapi:

这里进入E:\programfiles\softtools\Yapi\my-yapi目录下执行命令

node vendors/server/app.js

启动成功之后如下图：

这里说明一下，yapi的接口文档是以项目为维度的，所以跟springboot的微服务工程是一致的，因此口径上不太一致，创建项目之后，就可以手动维护接口了，这里通过easyyapi的配置自动导出。每个yapi的项目中有个token字段，需要通过easyyapi-idea插件配置一下这里简要说明一下，如下图是我创建的房源域项目，token是一串字符串：

根据官方的设置文档，我们需要做一些配置以链接到yapi，做认证，如下图：

配置完成之后就可以愉快的进行接口api管理了~

我最近整了一个公众号，持续输出原创内容，敬请关注：