springboot项目使用Swagger自动生成api文档

一、 文章介绍
本文使用Swagger解决前后端分离开发的时候，后端接口修改时，线上版本与api文档不一致的问题。

二、Swagger实现

1. pom.xml文件添加内容

<!-- swagger2 配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

2. 编写Swagger配置类

 @Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * @Description:swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.edu.controller"))
                .paths(PathSelectors.any()).build();
    }

    /**
     * @Description: 构建 api文档的信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置页面标题
                .title("标题")
                // 设置联系人
                .contact(new Contact("name", "url", "email"))
                // 描述
                .description("文档描述信息")
                // 定义版本号
                .version("1.0").build();
    }
}

注意：代码中的"com.edu.controller"需要改成自己controller层的位置。
访问：http://localhost:8080/swagger-ui.html 查看生成的api界面

3. 给controller添加名字
   添加@Api(value = “用户业务接口”,tags = {“用户相关业务的controller”})

@Controller
@RequestMapping("/user")
@Api(value = "用户业务接口",tags = {"用户相关业务的controller"})
public class UserController {
}

4. 给每个接口起名字
   添加 @ApiOperation(value = “注册”)

@ApiOperation(value = "注册")
    @PostMapping("/register")
    @ResponseBody

    public ServerResponse register(@Validated({User.LoginGroup.class}) User user){
    }

点击controller后发现我们添加注释的接口后面跟了一个注册的中文名字。

5. 给接口传递的参数起名字
   这里有两种方式，一种是传递对象，一种是直接传递参数。
   1. 传递对象

@ApiModel(value = "用户对象",description = "这是用户对象 ")
public class User {

    @ApiModelProperty(value = "用户名",required = true)
    private String username;

    @ApiModelProperty(value = "密码",required = true)
    private String password;

    @ApiModelProperty(value = "验证码",required = true)
    private String authcode;

    @ApiModelProperty(hidden = true)
    private String salt;

注意：如果设置了hidden = true，那么文档里面上传的参数就不会显示出来
解释：value(属性简要说明)、required(是否为必传参数)

2. 直接传递参数

 @ApiOperation(value = "注册")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "authcode", value = "验证码", required = false, dataType = "String", paramType = "form"),
    })
    @PostMapping("/register")
    @ResponseBody
    public ServerResponse register(String username，String password,String authcode){
    }

6. 测试接口
   输入参数后，直接输入点击try it out！即可