Spring Boot + Swagger2

首先swagger2的依赖

<!--swagger文档生成工具 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>${swagger.version}</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>${swagger.version}</version>
</dependency>

版本为 2.7.0

swagger2的配置，指定controller包名

/**
 * @author
 * @Description:swagger配置类
 * @date 2018/3/23 10:55
 */
@Configuration
@Profile({"!release", "!pro", "!master"})
public class Swagger2Config {
@Bean
    Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.lixy.boothigh.controller"))
                .paths(PathSelectors.any())
                .build()
                .directModelSubstitute(Timestamp.class, Long.class);
    }

    @Bean
    ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(" boot-high api docs")
                .version("1.0.0")
                .termsOfServiceUrl("www.baidu.com")
                .license("")
                .licenseUrl("www.baidu.com")
                .build();
    }
}

springboot 启动类

@MapperScan("com.lixy.boothigh.dao")
@SpringBootApplication
@EnableSwagger2/*swagger2启动*/
public class BootHighApplication {

   public static void main(String[] args) {
      SpringApplication.run(BootHighApplication.class, args);
   }
}

引入了一个注解@EnableSwagger2来启动swagger注解。RequestHandlerSelectors.basePackage("com.lixy.boothigh.controller")，指定swagger生效的包名下的所有controller

controller使用事例

@Api(tags = {"test使用接口"})
@RequestMapping("/test")
@RestController
public class TestIndexController {


    /**
     * @Author: MR LIS
     * @Description: swagger测试方法 使用详情参考:https://blog.csdn.net/molashaonian/article/details/72998428
     * @Date: 11:04 2018/4/19
     * @return
     */
    @ApiOperation(value = "swagger测试方法", notes = "swagger测试方法", response = JsonResult.class)
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="admin"),
            @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="123456"),
            @ApiImplicitParam(paramType="path",name="phone",dataType="String",required=true,value="手机号",defaultValue="")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
    })
    @PostMapping("/swagger/{phone}")
    public JsonResult swaggerMethod(@RequestParam("username") String username, @RequestParam("password") String password, @PathVariable("phone")String phone) {
        JsonResult jsonResult = new JsonResult();
        return jsonResult;
    }
}

如果ApiImplicitParam中的phone的paramType是query的话，是无法注入到rest路径中的，而且如果是path的话，是不需要配置ApiImplicitParam的，即使配置了，其中的value="手机号"也不会在swagger-ui展示出来。

浏览器输入：http://localhost:8080/swagger-ui.html

测试效果图

说明：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- paramType：参数放在哪个地方
  - header-->请求参数的获取：@RequestHeader
  - query-->请求参数的获取：@RequestParam
  - path（用于restful接口）-->请求参数的获取：@PathVariable
  - body（不常用）
  - form（不常用）
- name：参数名
- dataType：参数类型
- required：参数是否必须传
- value：参数的意思
- defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
- @ApiModelProperty：描述一个model的属性

具体其他的注解，查看：

https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

springfox官方文档: https://springfox.github.io/springfox/docs/snapshot/#introduction

参考：https://blog.csdn.net/molashaonian/article/details/72998428