SpringBoot 与 Swagger 整合

号称世界上最流行的Api框架 RestFul 风格的 Api 文档在线自动生成工具 ==> 制作API 文档 与 API 定义同步更新 可直接运行，可以在线测试API接口

官网：https://swagger.io/

在项目中使用Swagger 需要 Springfox

• Swagger2
• UI

SpringBoot集成Swagger

注意：最新的Swagger3.0是一个突破性的版本，和之前的版本在配置上，甚至于访问路径上都有很大的不同，这里为了和大众保持一致，使用3.0以前的版本，3.0的版本大家可以参考这篇文章：https://blog.csdn.net/weixin_44203158/article/details/109137799

1、导入Maven坐标

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2、配置Swagger

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

}

3、快速运行

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

4、简单配置

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //设置api监控，一般都是controller包，也可以设置所有RequestHandlerSelectors.any()
                .apis(RequestHandlerSelectors.basePackage("com.yingside.springbootdemo.controller"))
                .paths(PathSelectors.any()) // 对所有路径进行监控
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("yingside", "http://www.yanhongzhi.com/", "yif422@163.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

5、Controller

@Controller
@RequestMapping("/user")
@Api(tags="用户相关操作接口")
public class UserController {
    @PostMapping("/add")
    @ApiOperation("用户添加")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username",value="用户注册名",defaultValue = "zs",required = true),
            @ApiImplicitParam(name="nickname",value="用户昵称",defaultValue = "张三",required = true)
    })
    @ResponseBody
    public User addUser(@RequestParam(required = true)String username, String nickname) {
        return new User();
    }

    @GetMapping("/{id}")
    @ApiOperation("根据id查询用户的接口")
    @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "1", required = true)
    @ResponseBody
    public User getUserById(@PathVariable("id") Integer id) {
        System.out.println("id = " + id);
        User user = userService.getById(id);

        return user;
    }
    @PutMapping("/update")
    @ApiOperation("根据id更新用户的接口")
    @ResponseBody
    public User updateUserById(@RequestBody User user) {
        return user;
    }
}

1. @Api注解可以用来标记当前Controller的功能。
2. @ApiOperation注解用来标记一个方法的作用。
3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5. 需要注意的是，@ApiImplicitParam不能代替@RequestParam(required = true)
6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

@Data
@EqualsAndHashCode(callSuper = true)
@TableName("t_user")
@ApiModel(value = "用户pojo对象",description = "这是用户对象 ")
public class User extends Model{
    private static final long serialVersionUID = 1L;
    @ApiModelProperty("用户主键id")
    @TableId(value = "user_pkid", type = IdType.AUTO)
    private Integer userPkid;
    @ApiModelProperty("用户注册名")
    private String username;
    @ApiModelProperty("用户密码")
    private String password;
    @ApiModelProperty("用户昵称")
    private String nickname;
    @ApiModelProperty("注册时间")
    private LocalDateTime regTime;
    @ApiModelProperty(hidden = true)//hidden = true 不在api文档中显示
    private Integer fkDetailId;
    @ApiModelProperty(hidden = true)
    private Integer fkDeptId;
    @ApiModelProperty(hidden = true)
    @TableLogic
    private Integer deleted;
}