一、简介
- smart-doc介绍
- 创建md、html等格式的接口文档 - showdoc-在线API文档、技术文档工具
- 保存、预览接口文档，开源，可以自己部署服务
- 支持手动创建 和 上传。
二、smart-doc 使用注意事项、总结
基础使用，看官方文档
1、可以通过 packageFilters 参数，设置需要生成文档的包
config.setPackageFilters("com.power.doc.controller");
2、@ignore 注解，忽略某个接口，不生成文档
/*** 煤矿日报详情* @param reportSubmitId* @ignore*/@ApiOperation(value = "煤矿日报详情")@GetMapping(value = "/mineDayReportInfo")
3、@ignore注解，忽略某个属性，不生成文档
/*** 公司id* @ignore*/private String companyId ;
4、@ignore 注解 只能用于注释里面，接口则接口被忽略，
5、@ignore 用于某个类中的属性值注释的时候
① 这个类作为入参时，这个类中使用@ignore的属性被忽略，不生成入参文档
@这个类作为返回值，@ignore不起作用
6、不支持自定义某个controller 被忽略。
7、如下入参 ，默认生成文档 ：必填=true ，需要设置不是必填，或者忽略，需要创建为对象。
public InterceptorResult getMonthReportList(String companyType, String dateStr) {List<ReportListVO> result = service.getMonthReportList(companyType, dateStr);return InterceptorResult.success(result);
}
8、包含属性的类作为入参，里面所有属性默认：必填= false
可以通过@required 设置为必填，
/*** 性别* @required*/private int gender;
9、生成文档，如果返回值使用的对象不是本项目，而是引用的依赖。必须引入源码才可以生成注释。不然只有属性，没有注释。
// 本实例 是引入依赖的方式引源码配置如下， config.setSourceCodePaths(SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),//smart-doc对路径自动会做处理，无论是window合适linux系统路径，直接拷贝贴入即可SourceCodePath.path().setDesc("模块A").setPath("D:\\workspace\\A\\src\\main\\java"),SourceCodePath.path().setDesc("模块B").setPath("D:\\workspace\\B\\src\\main\\java"),SourceCodePath.path().setDesc("模块C").setPath("D:\\workspace\\C\\src\\main\\java"));最新版本smart-doc支持使用插件+配置文件，引入源码的方式见官网
三、使用showdoc对外开发api，将生成的文件上传到服务器。
- 一般方案：
- 上传的是写死的，可以根据实际，动态获取某个文件夹，遍历所有文件，读取每个文件标题、内容 ，来实现动态的上传。
- 好方案
- 读smart-doc源码，创建文件的时候，同时调用showdoc 上传方法，一次性到位。
主函数：
import com.power.common.util.CollectionUtil;
import java.util.ArrayList;
import java.util.List;
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 org.junit.Test;
import org.springframework.util.Assert;/**
* MarkDown文档Post提交信息
* @author zqk
* @since 2020/01/06
*/
public class JulyShowDocUtil {private static final String URL = "https://www.showdoc.cc/server/api/item/updateByApi";@Testpublic void run() throws Exception {ShowDoc showDoc = new ShowDoc();showDoc.setIsOpenLocal(true);showDoc.setApiKey("9c48e860b2c19b99246c0935f182fe6e1697272353");showDoc.setApiToken("c00e332741716cfdb1fcf1dc4218c773990482252");showDoc.setShowDocUrl(URL);List<ShowDocModel> list = new ArrayList<>();ShowDocModel showDocModel = new ShowDocModel();showDocModel.setEncode(true);showDocModel.setFolder("测试上传/测试"); // 设置文件夹结构showDocModel.setTitle("我是一个接口"); //设置文件名showDocModel.setContent("支持md文件字符串 或者 html 字符串"); //文件内容list.add(showDocModel);showDoc.setShowDocModels(list);doPost(showDoc);}public static void doPost(ShowDoc showDoc) throws Exception {if(showDoc.getIsOpenLocal()){Assert.hasText(showDoc.getShowDocUrl(), "show doc地址不能为空！");Assert.hasText(showDoc.getApiKey(), "apiKey不能为空！");Assert.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 );// 第三步：构造list集合，往里面丢数据List<NameValuePair> 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");System.out.println(str);//关闭response.close();}catch (Exception e){e.printStackTrace();}}}
相关类：
@Data
public 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<ShowDocModel> showDocModels;}@Data
public class ShowDocModel {/*** 标题*/private String folder;/*** 标题*/private String title;/*** 内容*/private String content;/*** 是否encode*/private boolean encode = true;}
参考资料：
1、如何把生成的接口文档，同步到showdoc 文档管理系统？
2、公共号关注 ： 程序员的故事
