Spring boot 优雅集成 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>

配置文件

简单配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.djy.demo.controller"))//扫描包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口的文档").description("这里是说明").version("1.0").build();
    }
}

多环境安全配置

在线上生产环境下我们是不需要将swagger暴露的，那么此时我们需要对swagger进行关闭

#swagger 开关
swagger2:
  enable: true

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //swagger 开关
    @Value("${swagger.enable}")
    private boolean enable;

    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.djy.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                //控制swagger开启/关闭
                .enable(enable);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口的文档").description("这里是说明").version("1.0").build();
    }
}

enable 用来控制swagger开启或关闭

swagger 添加请求头

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //swagger 开关
    @Value("${swagger2.enable}")
    private boolean enable;

    @Bean
    public Docket createDocket() {
        //头部信息集合
        List<Parameter> parameterList = new ArrayList();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        parameterBuilder.name("token").description("描述").modelRef(new ModelRef("String")).parameterType("header").required(false);
        parameterList.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.djy.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                //配置头部信息集合
                .globalOperationParameters(parameterList)
                //控制swagger开启/关闭
                .enable(enable);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口的文档").description("这里是说明").version("1.0").build();
    }
}

代码使用

@Data
public class ApiUserVO {

    @ApiModelProperty(value = "主键")
    private String id;

    @ApiModelProperty(value = "密码")
    private String username;

}

@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口")
public class SaggerController {

    @ApiOperation(value = "这是第一个swagger接口")
    @PostMapping("/swagger")
    public SwaggerVO testSwagger(@RequestBody SwaggerVO vo) {
        return vo;
    }
}

访问http://localhost:8080/swagger-ui.html

常用注解说明

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明：

@Api()
用于类；表示标识这个类是swagger的资源
tags - 表示说明
value - 也是说明，可以使用tags替代
description - 右侧说明

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController { }

@ApiOperation()
用于方法；表示一个http请求的操作
value - 用于方法描述
notes - 用于提示内容
tags可以重新分组（视情况而用）

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

@ApiIgnore()
用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例

@ApiImplicitParam()
用于方法
表示单独的请求参数

@ApiImplicitParams()
用于方法，包含多个 @ApiImplicitParam
name - 参数名
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() {
    }