文檔
swagger-doc
重點先說說這個項目解決了什麼問題
這個總得來說是給swagger解決了大部分人不想用swagger的問題，springfox的注解污染代碼，可以來看看用springfox時候的代碼
@GetMapping("/v1/index/banner")
@ApiOperation(value = "擷取首頁Banner", response = BannerJsonDto.class)
@ApiResponse(code = 200, message = "success")
public ResultUtils.ObjectResult getBanners() {
.....
return ResultUtils.ToObjectResult(bannerJsonDtos);
}
如上所示，如果用swagger就會産生這種無用的注解，但是還沒法不加 OK 繼續來看看swagger-doc同樣的代碼應該怎麼寫
@GetMapping("/select/like")
public ResponseEntity selectLike(@Valid QueryParam querParam) {
......
return ResponseEntity.success(pageResponse);
}
對比兩種使用方式，我想大多數人都會喜歡下面一種方式，因為doc是大部分代碼種不可少的東西，我了解的是如果大家在寫javadoc的同時順便把文檔也寫完了，是不是提高了很好的效率
是以就有此項目誕生
###優點缺點對比
項目
代碼污染
學習成本
支援springboot
功能完善程度
swagger-doc
java原生注解即可
低
支援
目前功能比較少
springfox
污染比較大
高
支援
完善
##快速開始
由于本項目還在建構中，是以沒有扔到mvncenter，是以先通過mvn install 到本地倉庫即可
###1.安裝到本地倉庫
cdswagger-doc
mvn install
###2.項目中使用
oszrh
https://oss.sonatype.org/content/repositories/snapshots
com.gitee.largerfish
swagger-core
1.1-SNAPSHOT
###3.spring boot 配置
@EnableSwaggerDoc
public class SampleApplication {
public static void main(String[] args) {
SpringApplication springApplication = new SpringApplication(SampleApplication.class);
springApplication.run(args);
}
@Bean
public FilterRegistrationBean logFilterRegistrationBean() {
FilterRegistrationBean filterRegistrationBean = new FilterRegistrationBean();
filterRegistrationBean.setFilter(new FilterInterceptor());
filterRegistrationBean.setName("logFilterRegistrationBean");
filterRegistrationBean.setUrlPatterns(Arrays.asList("/*"));
filterRegistrationBean.setOrder(1);
return filterRegistrationBean;
}
@Bean
public SwaggerDoc swaggerDoc() {
Contact contact = new Contact();
Info info = new Info();
info.setTitle("測試文檔");
contact.setEmail("[email protected]");
contact.setName("wk");
contact.setUrl("http://git.oschina.net/wangkang_daydayup/swagger-doc");
info.setDescription("swagger-doc解決了springfox用注解污染代碼的問題，采用原生java-doc來實作文檔的生成，讓代碼更加幹淨，學習成本更低");
info.setContact(contact);
return new SwaggerDoc.SwaggerDocBuilder().addSkipAnnotations(SessionAttribute.class).withDoc("doc")
.withDoc("測試文檔").withInfo(info).withHost("139.224.35.224")
.addIgnoreControllers("swaggerController", "basicErrorController").build();
}
}
###4. 打包源碼
這裡是最重要的一點，因為java編譯後會把doc擦除，這就是為什麼class檔案裡面很少能看見注釋，是以需要利用源碼來進行解析,是以需要使用maven插件
org.apache.maven.plugins
maven-source-plugin
3.0.1
attach-sources
jar-no-fork
打包時把源碼拷貝到source中
#!/usr/bin/env bash
mvn clean -U process-resources package -Dmaven.test.skip=true
cptarget/swagger-doc-demo-1.0-SNAPSHOT.jar source
###5 搭建swagger-ui
下載下傳最新版swagger-ui
總體來說使用方式很簡單，上面的quickstart僅僅隻用于單子產品項目，也就是說dto跟api在同一個項目裡面，多子產品複雜項目會在接下倆的文檔裡面繼續講解
###效果圖
###測試連結