基础使用,看官方文档
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 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支持使用插件+配置文件,引入源码的方式见官网
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 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 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 showDocModels;
}
@Data
public class ShowDocModel {
/**
* 标题
*/
private String folder;
/**
* 标题
*/
private String title;
/**
* 内容
*/
private String content;
/**
* 是否encode
*/
private boolean encode = true;
}