SpringBoot整合Swagger2

1、Swagger2简介

Swagger2主要是用于生成在线的RESTful API文档，让维护文档和修改代码整合为一体，在修改代码逻辑的同时方便地修改文档说明

2、添加依赖

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

3、主启动类上添加@EnableSwagger2注解

@SpringBootApplication
@EnableSwagger2
@MapperScan("com.hand.cms.mapper")
public class CmsApplication {

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

}

4、配置类

@Configuration
public class Swagger2Config {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.hand.cms"))
                    .paths(PathSelectors.any())
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("看点资讯管理系统API文档")
                    .description("看点资讯管理系统,http://localhost:8080/")
                    .termsOfServiceUrl("http://localhost:8080/")
                    .version("1.0")
                    .build();
        }
}

5、相关注解

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiModelProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

6、项目中具体使用

1）、实体Bean

@Data
public class BaseDomain implements Serializable {
    @ApiModelProperty(value = "主键ID")
    @TableId(value = "id")
    protected Long id;

    @ApiModelProperty(value = "创建日期")
    @TableField(value = "created_date", fill = FieldFill.INSERT)
    protected String createdDate;

    @ApiModelProperty(value = "最后更新日期")
    @TableField(value = "last_updated_date", fill = FieldFill.INSERT_UPDATE)
    protected String lastUpdatedDate;

    /**
     * 乐观锁实现方式：
     * 取出记录时，获取当前version
     * 更新时，带上这个version
     * 执行更新时， set version = newVersion where version = oldVersion
     * 如果version不对，就更新失败
     */
    @ApiModelProperty(value = "版本号")
    @TableField(value = "version_number", strategy = FieldStrategy.NOT_NULL)
    @Version
    protected Integer versionNumber;

    /**
     * 逻辑删除
     * 使用mybatis-plus自带方法删除和查找都会附带逻辑删除功能(自己写的xml不会)
     */
    @ApiModelProperty(value = "是否被删除")
    @TableField(value = "deleted", strategy = FieldStrategy.NOT_NULL)
    @TableLogic
    protected Integer deleted;

}

@ApiModel(value = "用户")
@TableName(value = "user")
@Data
public class User extends BaseDomain {
    /**
     * 用户名
     */
    @ApiModelProperty(value = "用户名")
    @TableField("username")
    private String username;

    /**
     * 真实姓名
     */
    @ApiModelProperty(value = "真实姓名")
    @TableField("real_name")
    private String realName;

    /**
     * 密码
     */
    @ApiModelProperty(value = "密码")
    @TableField("password")
    private String password;

    /**
     * 邮箱
     */
    @ApiModelProperty(value = "邮箱")
    @TableField("email")
    private String email;
}

2）、Controller

@Api(tags = "用户相关")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "用户分页查询", notes = "用户分页查询")
    @GetMapping("/list")
    public ResponseEntity<List<User>> getUserPage(@ApiParam(value = "当前页") @RequestParam(value = "page", defaultValue = "1") int page,
                                                  @ApiParam(value = "每页多少条") @RequestParam(value = "size", defaultValue = "10") int size) {
        Page mybatisPage = new Page(page, size);
        IPage<User> userPage = userService.getUserPage(mybatisPage);
        HttpHeaders httpHeaders = PageUtils.getTotalHeader(mybatisPage);
        return new ResponseEntity<>(userPage.getRecords(), httpHeaders, HttpStatus.OK);
    }

    @ApiOperation(value = "根据用户名获取用户信息", notes = "根据用户名获取用户信息")
    @GetMapping("/getUserByUsername")
    public ResponseEntity<List<User>> getUserByUsername(@ApiParam(value = "用户名") @RequestParam(value = "username", required = false) String username) {
        List<User> user = userService.getUserByUsername(username);
        return new ResponseEntity<>(user, HttpStatus.OK);
    }

    @ApiOperation(value = "添加用户信息", notes = "添加用户信息")
    @PostMapping("/insert")
    public ResponseEntity insertUser(@ApiParam(value = "用户信息") @RequestBody User user) {
        userService.insertUser(user);
        return new ResponseEntity<>(HttpStatus.OK);
    }

    @ApiOperation(value = "更新用户信息", notes = "更新用户信息")
    @PutMapping("/update")
    public ResponseEntity updateUser(@ApiParam(value = "用户信息") @RequestBody User user) {
        userService.updateUser(user);
        return new ResponseEntity<>(HttpStatus.OK);
    }

    @ApiOperation(value = "根据ID删除用户", notes = "根据ID删除用户")
    @DeleteMapping("/deleteById")
    public ResponseEntity deleteUserById(@ApiParam(value = "主键ID") @RequestParam(value = "id") Long id) {
        userService.deleteUserById(id);
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

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