showdoc如何创建文件夹_如何把生成的接口文档，同步到showdoc 文档管理系统？

关注程序员7歌，一起用技术改变世界

showdoc：简介在线文档管理系统很多, 比如阿里的语雀、腾讯的 TAPD 平台也包括文档管理功能, 但这些系统需要联网的, 企业内文档协作工具不是很多, 最有名的是收费的 confluence 了, 禅道有文档管理功能, 但功能较弱, 比较适合附件上传管理.

这里介绍 Showdoc这款开源(免费)文档管理系统，可以部署企业内部，后台使用 php + sqlite，支持 Windows/Linux/Docker 部署形式。

showdoc 的功能:

1. 文档编辑语法采用 markdown, 编辑器做的挺不错。

2. 支持文档版本管理

3. 可以将文档导出为 word 软件格式

4. 权限控制: 可以新建公开项目和私密项目, 可以管理项目成员。

5. 文档搜索功能: 可以在一个项目搜索文档, 支持全文搜索, 但不支持跨项目的搜索。

之前的文章我们讲过自动生成接口文档，今天我将为大家讲解把工具(July Doc)生成的MarkDown格式的接口文档自动同步到showdoc管理系统。

在接口生成工具上创建showdoc实体对象ShowDocModel，用于传递showdoc参数，代码如下：

package com.july.doc.showdoc;import lombok.Data;/*** showdoc信息* @author zqk* @since 2019/12/11*/@Datapublic class ShowDocModel {/*** 标题*/private String folder;/*** 标题*/private String title;/*** 内容*/private String content;/*** 是否encode*/private boolean encode = true;}

参数解析：

folder：showdoc的目录名称，多级目录格式为：一级目录/二级目录/三级目录

title：接口文档标题

content：接口文档内容

创建showdoc上传接口文档的工具类，通过调用showdoc的开放API，实现接口文档的同步功能，代码如下：

package com.july.doc.showdoc;import com.july.doc.utils.AssertUtil;import com.july.doc.utils.CollectionUtil;import org.apache.http.HttpEntity;import org.apache.http.NameValuePair;import org.apache.http.client.entity.UrlEncodedFormEntity;import org.apache.http.client.methods.CloseableHttpResponse;import org.apache.http.client.methods.HttpPost;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.impl.client.HttpClients;import org.apache.http.message.BasicNameValuePair;import org.apache.http.util.EntityUtils;import java.util.ArrayList;import java.util.List;/*** MarkDown文档Post提交信息* @author zqk* @since 2020/01/06*/public class JulyShowDocUtil{private static final String URL = "/server/index.php?s=/api/item/updateByApi";public static void doPost(ShowDoc showDoc) throws Exception{if(!showDoc.getIsOpenLocal()){AssertUtil.hasText(showDoc.getShowDocUrl(), "show doc地址不能为空！");AssertUtil.hasText(showDoc.getApiKey(), "apiKey不能为空！");AssertUtil.hasText(showDoc.getApiToken(), "apitoken不能为空！");if(CollectionUtil.isEmpty(showDoc.getShowDocModels())){throw new Exception("Please provide markdown information！");}else{for (ShowDocModel showDocModel : showDoc.getShowDocModels()) {HttpClientPost(showDoc.getShowDocUrl(),showDoc.getApiKey(),showDoc.getApiToken(),showDocModel);}}}}/*** 构建post请求* @param showDocUrl* @param apiKey* @param apiToken* @param showDocModel* @author zqk* @since 2020/01/06*/public static void HttpClientPost(String showDocUrl,String apiKey,String apiToken,ShowDocModel showDocModel){try{// 获取默认的请求客户端CloseableHttpClient client = HttpClients.createDefault();// 通过HttpPost来发送post请求HttpPost httpPost = new HttpPost(showDocUrl + URL);// 第三步：构造list集合，往里面丢数据List list = new ArrayList<>();BasicNameValuePair basicNameValuePair = new BasicNameValuePair("api_key", apiKey);BasicNameValuePair basicNameValuePair2 = new BasicNameValuePair("api_token", apiToken);BasicNameValuePair basicNameValuePair3 = new BasicNameValuePair("cat_name", showDocModel.getFolder());BasicNameValuePair basicNameValuePair4 = new BasicNameValuePair("page_title", showDocModel.getTitle());BasicNameValuePair basicNameValuePair5 = new BasicNameValuePair("page_content", showDocModel.getContent());list.add(basicNameValuePair);list.add(basicNameValuePair2);list.add(basicNameValuePair3);list.add(basicNameValuePair4);list.add(basicNameValuePair5);//第二步：我们发现Entity是一个接口，所以只能找实现类，发现实现类又需要一个集合，集合的泛型是NameValuePair类型UrlEncodedFormEntity formEntity = new UrlEncodedFormEntity(list,"UTF-8");//第一步：通过setEntity，将我们的entity对象传递过去httpPost.setEntity(formEntity);//HttpEntity//是一个中间的桥梁，在httpClient里面，是连接我们的请求与响应的一个中间桥梁，所有的请求参数都是通过HttpEntity携带过去的//通过client来执行请求，获取一个响应结果CloseableHttpResponse response = client.execute(httpPost);HttpEntity entity = response.getEntity();String str = EntityUtils.toString(entity, "UTF-8");//关闭response.close();}catch (Exception e){e.printStackTrace();}}}

上面的工具类用到自定义实体对象ShowDoc(接口工具需要的，自用可以不要)，代码如下：

package com.july.doc.showdoc;import lombok.AllArgsConstructor;import lombok.Data;import java.util.List;/*** show doc网站信息* @author zqk* @since 2020/01/06*/@Data@AllArgsConstructorpublic class ShowDoc {/*** 是否上传show doc*/private Boolean isOpenLocal;/*** show doc部署地址*/private String showDocUrl;/*** show doc open api key*/private String apiKey;/*** show doc open api token*/private String apiToken;/*** markdown文档信息*/private List showDocModels;}

参数解析：

isOpenLocal：是否生成本地接口文档

showDocUrl：showdoc管理系统地址

apiKey：showdoc开放API的api key

apiToken：showdoc开放API的api token

同步接口文档到showdoc时，调用doPost方法即可，如下代码：

config.setIsOpenLocal(true);config.setFolder("测试/测试");//获取所有的Markdown文件List showDocModels = JulyDoc.generateOneApi(config);//上传markdown文档至show docJulyShowDocUtil.doPost(new ShowDoc(config.getIsOpenLocal(), showdoc_url, app_key, app_token, showDocModels));

以上的showDocModels就是MarkDown的信息，下面为测试demo，如下图：

上面就是通过showdoc的开放API同步接口文档的教程，对于自动生成接口文档的小伙伴非常有用的，关于自动生成接口文档工具(July Doc)想要了解的小伙伴可以私信咨询我。