<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>

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration // 標(biāo)明是配置類
@EnableSwagger2 //開啟swagger功能
public class SwaggerConfig {
 @Bean
 public Docket createRestApi() {
 return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2
//  .groupName("分布式任務(wù)系統(tǒng)") // 如果配置多個(gè)文檔的時(shí)候，那么需要配置groupName來(lái)分組標(biāo)識(shí)
  .apiInfo(apiInfo()) // 用于生成API信息
  .select() // select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制接口被swagger做成文檔
  .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定掃描哪個(gè)包下的接口
  .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔，可以配置這里
  .build();
 }

 /**
 * 用于定義API主界面的信息，比如可以聲明所有的API的總標(biāo)題、描述、版本
 * @return
 */
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
  .title("XX項(xiàng)目API") // 可以用來(lái)自定義API的主標(biāo)題
  .description("XX項(xiàng)目SwaggerAPI管理") // 可以用來(lái)描述整體的API
  .termsOfServiceUrl("") // 用于定義服務(wù)的域名
  .version("1.0") // 可以用來(lái)定義版本。
  .build(); //
 }
}

@Api(tags = "角色管理") // tags：你可以當(dāng)作是這個(gè)組的名字。
@RestController
public class RoleController {
}

@Api(tags = "用戶管理") // tags：你可以當(dāng)作是這個(gè)組的名字。
@RestController
public class UserController {
}

@Api(tags = "用戶管理")
@RestController
public class UserController {
 // 注意，對(duì)于swagger，不要使用@RequestMapping，
 // 因?yàn)锧RequestMapping支持任意請(qǐng)求方式，swagger會(huì)為這個(gè)接口生成7種請(qǐng)求方式的接口文檔
 @GetMapping("/info") 
 public String info(String id){
 return "aaa";
 }
}

@ApiOperation(value = "用戶測(cè)試",notes = "用戶測(cè)試notes")
 @GetMapping("/test")
 public String test(String id){
 return "test";
 }

// 先使用@ApiModel來(lái)標(biāo)注類
@ApiModel(value="用戶登錄表單對(duì)象",description="用戶登錄表單對(duì)象")
public class LoginForm {
 // 使用ApiModelProperty來(lái)標(biāo)注字段屬性。
 @ApiModelProperty(value = "用戶名",required = true,example = "root")
 private String username;
 @ApiModelProperty(value = "密碼",required = true,example = "123456")
 private String password;

 // 此處省略入?yún)①x值時(shí)需要的getter,setter,swagger也需要這個(gè)
}

 @ApiOperation(value = "登錄接口",notes = "登錄接口的說(shuō)明")
 @PostMapping("/login")
 public LoginForm login(@RequestBody LoginForm loginForm){
 return loginForm;
 }

 // 使用URL query參數(shù)
 @ApiOperation(value = "登錄接口2",notes = "登錄接口的說(shuō)明2")
 @ApiImplicitParams({
  @ApiImplicitParam(name = "username",//參數(shù)名字
   value = "用戶名",//參數(shù)的描述
   required = true,//是否必須傳入
   //paramType定義參數(shù)傳遞類型：有path,query,body,form,header
   paramType = "query"
   )
  ,
  @ApiImplicitParam(name = "password",//參數(shù)名字
   value = "密碼",//參數(shù)的描述
   required = true,//是否必須傳入
   paramType = "query"
   )
 })
 @PostMapping(value = "/login2")
 public LoginForm login2(String username,String password){
 System.out.println(username+":"+password);
 LoginForm loginForm = new LoginForm();
 loginForm.setUsername(username);
 loginForm.setPassword(password);
 return loginForm;
 }

 // 使用路徑參數(shù)
 @PostMapping("/login3/{id1}/{id2}")
 @ApiOperation(value = "登錄接口3",notes = "登錄接口的說(shuō)明3")
 @ApiImplicitParams({
  @ApiImplicitParam(name = "id1",//參數(shù)名字
   value = "用戶名",//參數(shù)的描述
   required = true,//是否必須傳入
   //paramType定義參數(shù)傳遞類型：有path,query,body,form,header
   paramType = "path"
  )
  ,
  @ApiImplicitParam(name = "id2",//參數(shù)名字
   value = "密碼",//參數(shù)的描述
   required = true,//是否必須傳入
   paramType = "path"
  )
 })
 public String login3(@PathVariable Integer id1,@PathVariable Integer id2){
 return id1+":"+id2;
 }

 // 用header傳遞參數(shù)
 @PostMapping("/login4")
 @ApiOperation(value = "登錄接口4",notes = "登錄接口的說(shuō)明4")
 @ApiImplicitParams({
  @ApiImplicitParam(name = "username",//參數(shù)名字
   value = "用戶名",//參數(shù)的描述
   required = true,//是否必須傳入
   //paramType定義參數(shù)傳遞類型：有path,query,body,form,header
   paramType = "header"
  )
  ,
  @ApiImplicitParam(name = "password",//參數(shù)名字
   value = "密碼",//參數(shù)的描述
   required = true,//是否必須傳入
   paramType = "header"
  )
 })
 public String login4( @RequestHeader String username,
    @RequestHeader String password){
 return username+":"+password;
 }

 // 有文件上傳時(shí)要用@ApiParam，用法基本與@ApiImplicitParam一樣，不過(guò)@ApiParam用在參數(shù)上
 // 或者你也可以不注解，swagger會(huì)自動(dòng)生成說(shuō)明
 @ApiOperation(value = "上傳文件",notes = "上傳文件")
 @PostMapping(value = "/upload")
 public String upload(@ApiParam(value = "圖片文件", required = true)MultipartFile uploadFile){
 String originalFilename = uploadFile.getOriginalFilename();
 return originalFilename;
 }
 // 多個(gè)文件上傳時(shí)，**swagger只能測(cè)試單文件上傳**
 @ApiOperation(value = "上傳多個(gè)文件",notes = "上傳多個(gè)文件")
 @PostMapping(value = "/upload2",consumes = "multipart/*", headers = "content-type=multipart/form-data")
 public String upload2(@ApiParam(value = "圖片文件", required = true,allowMultiple = true)MultipartFile[] uploadFile){
 StringBuffer sb = new StringBuffer();
 for (int i = 0; i < uploadFile.length; i++) {
  System.out.println(uploadFile[i].getOriginalFilename());
  sb.append(uploadFile[i].getOriginalFilename());
  sb.append(",");
 }
 return sb.toString();
 }
 // 既有文件，又有參數(shù)
 @ApiOperation(value = "既有文件，又有參數(shù)",notes = "既有文件，又有參數(shù)")
 @PostMapping(value = "/upload3")
 @ApiImplicitParams({
  @ApiImplicitParam(name = "name",
   value = "圖片新名字",
   required = true
  )
 })
 public String upload3(@ApiParam(value = "圖片文件", required = true)MultipartFile uploadFile,
    String name){
 String originalFilename = uploadFile.getOriginalFilename();
 return originalFilename+":"+name;
 }

 // 返回被@ApiModel標(biāo)注的類對(duì)象
 @ApiOperation(value = "實(shí)體類響應(yīng)",notes = "返回?cái)?shù)據(jù)為實(shí)體類的接口")
 @PostMapping("/role1")
 public LoginForm role1(@RequestBody LoginForm loginForm){
 return loginForm;
 }

 // 其他類型的,此時(shí)不能增加字段注釋，所以其實(shí)swagger推薦使用實(shí)體類
 @ApiOperation(value = "非實(shí)體類",notes = "非實(shí)體類")
 @ApiResponses({
  @ApiResponse(code=200,message = "調(diào)用成功"),
  @ApiResponse(code=401,message = "無(wú)權(quán)限" )
 }
 )
 @PostMapping("/role2")
 public String role2(){
 return " {\n" +
  " name:\"廣東\",\n" +
  " citys:{\n" +
  "  city:[\"廣州\",\"深圳\",\"珠海\"]\n" +
  " }\n" +
  " }";
 }

 <!--引入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>
 <!-- 引入swagger-bootstrap-ui依賴包-->
 <dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.8.7</version>
 </dependency>

@Configuration // 標(biāo)明是配置類
@EnableSwagger2 //開啟swagger功能
@EnableSwaggerBootstrapUI // 開啟SwaggerBootstrapUI
public class SwaggerConfig {
 // 省略配置內(nèi)容
}

.antMatchers("/swagger**/**").permitAll()
.antMatchers("/webjars/**").permitAll()
.antMatchers("/v2/**").permitAll()
.antMatchers("/doc.html").permitAll() // 如果你用了bootstarp的Swagger UI界面，加一個(gè)這個(gè)。

//如果有額外的全局參數(shù)，比如說(shuō)請(qǐng)求頭參數(shù)，可以這樣添加
 ParameterBuilder parameterBuilder = new ParameterBuilder();
 List<Parameter> parameters = new ArrayList<Parameter>();
 parameterBuilder.name("authorization").description("令牌")
  .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
 parameters.add(parameterBuilder.build());
 return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2
  .apiInfo(apiInfo()) // 用于生成API信息
  .select() // select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制接口被swagger做成文檔
  .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定掃描哪個(gè)包下的接口
  .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔，可以配置這里
  .build().globalOperationParameters(parameters);

 // 如果需要額外的參數(shù)，非本方法用到，但過(guò)濾器要用,類似于權(quán)限token
 @PostMapping("/login6")
 @ApiOperation(value = "帶token的接口",notes = "帶token的接口")
 @ApiImplicitParams({
  @ApiImplicitParam(name = "authorization",//參數(shù)名字
   value = "授權(quán)token",//參數(shù)的描述
   required = true,//是否必須傳入
   paramType = "header"
  )
  ,
  @ApiImplicitParam(name = "username",//參數(shù)名字
   value = "用戶名",//參數(shù)的描述
   required = true,//是否必須傳入
   paramType = "query"
  )
 })
 public String login6(String username){
 return username;
 }