我是kacen汽纤,一個會點前端的java后端開發(fā)工程師。
今天來插曲一下洪添,來介紹一下Swagger的使用绅项。
簡介
??Swagger是為了解決企業(yè)中接口(api)中定義統(tǒng)一標準規(guī)范的文檔生成工具。方便各大后端小基友的懶問題赋续,但是寫注解也是妥妥的麻煩男翰,但是如果版本迭代快或者人員的流動性大,會導致很多問題纽乱。所以很多企業(yè)中都會有統(tǒng)一的規(guī)范文檔蛾绎,來定義接口標準。
注釋和參數(shù)講解
參數(shù)說明:
name -- 參數(shù)名
value --?參數(shù)說明
required -- 是否必須填寫
dataType -- 數(shù)據類型
paramType -- 參數(shù)類型
example -- 舉例
常用注解說明:
-
@Api()用于類鸦列;
表示標識這個類是swagger的資源
-
@ApiOperation()用于方法租冠;
表示一個http請求的操作
-
@ApiParam()用于方法,參數(shù)薯嗤,字段說明顽爹;
表示對參數(shù)的添加元數(shù)據(說明或是否必填等)
-
@ApiModel()用于類
表示對類進行說明,用于參數(shù)用實體類接收
-
@ApiModelProperty()用于方法骆姐,字段
表示對model屬性的說明或者數(shù)據操作更改
-
@ApiIgnore()用于類镜粤,方法捏题,方法參數(shù)
表示這個方法或者類被忽略
-
@ApiImplicitParam() 用于方法
表示單獨的請求參數(shù)
-
@ApiImplicitParams() 用于方法,包含多個 @ApiImplicitParam
具體使用說明:
1.@Api()
···
@Api("測試用例1")
@Controller
public class swaggerTestUse(){
}
2.@ApiOperation()
···
@Api("測試用例1")
@Controller
public class swaggerTestUse(){
@ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
public void apiOperationSwaggerTest(){
}
}
3.@ApiParam()
···
@Api("測試用例1")
@Controller
public class swaggerTestUse(){
@ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
public void apiOperationSwaggerTest(@ApiParam(name = "id", value = "id入參", required = true) Integer id){
}
}
4.@ApiModel()
···
@ApiModel(description = "測試實體類", value = "測試實體類")
public class Album implements Serializable {
···
}
5.@ApiModelProperty()
···
@ApiModel(description = "測試實體類", value = "測試實體類")
public class User implements Serializable {
@ApiModelProperty(name = "userName", value = "用戶名", required = false, exmaple = "小明")
private String userName;
}
6.@ApiImplicitParams() 和@ApiImplicitParam()這兩是兄弟就不分開寫了
···
@Api("測試用例1")
@Controller
public class swaggerTestUse(){
@ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入參", required = true, dataType = "Integer", paramType = "query"),
@ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
})
public void apiOperationSwaggerTest(Integer id, Brand band){
}
}
Swagger2實戰(zhàn)/Swagger具體使用說明(附帶環(huán)境參數(shù)開關配置和springboot WebConfiguration的實現(xiàn)過濾)
看完以上基本的使用說明繁仁,接下來我們就開始實戰(zhàn)吧I嫦凇!黄虱!
步驟1:當然是pom文件導入依賴
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
步驟2:啟動類添加@EnableSwagger2注解
@SpringBootApplication
@EnableSwagger2
@ComponentScan(basePackages = {""})//為什么寫這個稚矿,有的小伙伴掃不到包的請手動掃包
public class ServiceGoodsApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceGoodsApplication.class);
}
}
步驟3:編寫SwaggerConfig文件
@EnableSwagger2
@Configuration
//Profile是方法1(只在dev和test環(huán)境下開啟)
@Profile({"dev","test"})
public class SwaggerConfig implements WebMvcConfigurer {
//是否開啟swagger,正式環(huán)境一般是需要關閉的捻浦,可根據springboot的多環(huán)境配置進行設置
//這個是方法2哦晤揣,使用的話在new Docket里添加.Enable方法將參數(shù)放入即可
@Value(value = "${swagger.show}")
private Boolean swaggerEnabled;
/**
* apiInfo() 增加API相關信息
* 所有的注解
* .apis(RequestHandlerSelectors.any())
* 指定部分注解1.Api.class(@APi),2.ApiOperation.class(@ApiOperation),3.ApiImplicitParam.class(@ApiImplicitParam)
*.apis(RequestHandlerSelectors.withMethodAnnotation(Api.class))
* 指定包路徑
* .apis(RequestHandlerSelectors.basePackage("這里填寫需要的路徑"))
* .paths() 這個是包路徑下的路徑,PathSelectors.any()是包下所有路徑
*/
@Bean
public Docket createRestApi() {
log.info(""+swaggerEnabled);
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
//創(chuàng)建
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot-Swagger2集成")
.description("springboot | swagger")
// 作者信息
.contact(new Contact("kacen", "https://www.baidu.com", "abc@qq.com"))
.version("0.0.1")
.build();
}
//這個是可要可不要的,具體看需求
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
看到這里有小伙伴在想要指定多包路徑朱灿,但是又不要整個項目那要怎么辦呢昧识,讓我?guī)愀阋徊ǎ?br> 點擊這里看多包配置哦
步驟4:
大功告成啦,請輸入http://服務器ip:端口/swagger-ui.html#/看看你的專屬文檔吧
提示:
?對于是否暴露swagger盗扒,我提供的環(huán)境開關配置只是其中之一哦跪楞,更多的項目采用的是將頁面放到靜態(tài)頁面,再用nginx進行轉發(fā)后侣灶,指定代理環(huán)境訪問哦甸祭。想了解的可以自己試一下哦。