SpringBoot整合Swagger2 以及相关知识点详解

在上一篇记录了SpingBoot使用Restful风格实现增删改查 ，所以我们就在上一篇代码的基础上实现本节内容。因为现在很多都是前后端分离，所以有一份合理高效的API文档就很重要。虽然苦B的我平时项目中前后端都是自己做，但是该学的还是得学啊。好了，进入主题。

一、pom.xml

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

二、Swagger2配置类

在启动类的同目录下创建Swagger2的配置类

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 选择那些路径和api会生成document
                .paths(PathSelectors.any())
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                .apis(RequestHandlerSelectors.basePackage("com.example.restfuldemo.controller"))
                .build()
                .securitySchemes(security());
    }

    /**
     * 接口文档详细信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("这是我的接口文档")
                .contact(new Contact("LoneWalker", "", "LoneWalker@163.com"))
                .description("这是SWAGGER_2生成的接口文档")
                .version("v1.0")
                .build();
    }

    private List<ApiKey> security() {
        ArrayList<ApiKey> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("token", "token", "header"));
        return apiKeys;
    }
}

三、在类和方法上加上相关注解

@Api(tags = "用户信息接口")
@RestController
@RequestMapping("/api/user")
public class UserInfoController {

    @Autowired
    UserInfoService userInfoService;

    @ApiOperation("添加用户信息")
    @PostMapping
    public int addUser(UserInfo userInfo){
        return  userInfoService.addUser(userInfo);
    }

    @ApiOperation("更新用户信息")
    @PutMapping
    public int updateUser(UserInfo userInfo){
        return  userInfoService.updateUser(userInfo);
    }

    @ApiOperation("删除用户信息")
    @DeleteMapping
    public int delUser(int id){
        return userInfoService.delUser(id);
    }

    @ApiOperation("获取所有用户")
    @GetMapping("/userAll")
    public List<UserInfo> findAll(){
        return userInfoService.findAll();
    }

}

@ApiModel(value = "用户类")
public class UserInfo implements Serializable {

    @ApiModelProperty(value = "ID", example = "1")
    private Integer id;

    @ApiModelProperty("用户真实姓名")
    private String name;

    @ApiModelProperty("密码")
    private String password;

    @ApiModelProperty("盐值")
    private String salt;

    @ApiModelProperty("状态")
    private String state;

    @ApiModelProperty("用户账号")
    private String username;

运行项目，测试访问：http://localhost:8080/swagger-ui.html

四、相关知识点记录

4.1常用注解

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

4.2 提示

@ApiModelProperty描述Integer类型参数时，不加example会报

java.lang.NumberFormatException: For input string: ""