1、pom依賴
<!-- swagger2 -->
<!--swagger本身不支持spring mvc的,springfox把swagger包裝了一下,讓他可以支持springmvc-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
2、添加一個配置類
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.test.demo.web"))
.build();
}
public ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("api接口說明")
.version("1.0.0")
.build();
}
}
3、Controller
@Controller
@Api(value = "webcontroller")
public class WebController {
@ApiOperation(value = "獲取信息",notes = "獲取信息1",httpMethod = "GET")
@GetMapping("/get")
@ResponseBody
public Object get(){
Map map = new HashMap();
map.put("key1","nihao");
map.put("key2","nishi");
return map;
}
}
4、訪問
通過瀏覽器打開swagger-ui的web管理界面。
默認地址是IP:port/swagger-ui.html.
本地運行IP是127.0.0.1
5、常用註解
-
@Api()用於類;
表示標識這個類是swagger的資源 -
@ApiOperation()用於方法;
表示一個http請求的操作 -
@ApiParam()用於方法,參數,字段說明;
表示對參數的添加元數據(說明或是否必填等) -
@ApiModel()用於類
表示對類進行說明,用於參數用實體類接收 -
@ApiModelProperty()用於方法,字段
表示對model屬性的說明或者數據操作更改 -
@ApiIgnore()用於類,方法,方法參數
表示這個方法或者類被忽略 -
@ApiImplicitParam() 用於方法
表示單獨的請求參數 -
@ApiImplicitParams() 用於方法,包含多個 @ApiImplicitParam
6、具體使用舉例說明
@Api()
用於類;表示標識這個類是swagger的資源
tags–表示說明
value–也是說明,可以使用tags替代
但是tags如果有多個值,會生成多個list
@Controller
@Api(value="用戶controller",tags={"用戶操作接口"})
public class WebController {
}
@ApiOperation()用於方法;表示一個http請求的操作
value用於方法描述
notes用於提示內容
tags可以重新分組(視情況而用)
@ApiOperation(value = "獲取信息",notes = "獲取信息1",httpMethod = "GET")
@GetMapping("/get")
@ResponseBody
public Object get(){
Map map = new HashMap();
map.put("key1","nihao");
map.put("key2","nishi");
return map;
}
@ApiParam() 用於方法,參數
字段說明;表示對參數的添加元數據(說明或是否必填等)
name–參數名
value–參數說明
required–是否必填
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
@ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
// userService可忽略,是業務邏輯
User user = userService.getUserInfo();
return user;
}
}
@ApiModel()
用於類 ;表示對類進行說明,用於參數用實體類接收
value–表示對象名
description–描述
都可省略
@ApiModelProperty()
用於方法,字段; 表示對model屬性的說明或者數據操作更改
value–字段說明
name–重寫屬性名字
dataType–重寫屬性類型
required–是否必填
example–舉例說明
hidden–隱藏
@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用戶名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="狀態",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
@ApiModelProperty(value="id數組",hidden=true)
private String[] ids;
private List<String> idList;
//省略get/set
}
@ApiOperation("更改用戶信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){
int num = userService.updateUserInfo(user);
return num;
}
@ApiIgnore()用於類或者方法上,可以不被swagger顯示在頁面上
@ApiImplicitParam() 用於方法,表示單獨的請求參數
@ApiImplicitParams() 用於方法,包含多個 @ApiImplicitParam
name–參數ming
value–參數說明
dataType–數據類型
paramType–參數類型
example–舉例說明
@ApiOperation("查詢測試")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")})
public void select(){
}