smart-doc + showdoc 配合 管理项目接口文档

一、简介

• 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";

   @Test
   public 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、公共号关注 ： 程序员的故事