SpringBoot集成Swagger2在线文档

XuDanT

2019-12-22

关注关注

SpringBoot集成Swagger2在线文档

前言

不得不说，前后端分离开发的工作方式给我们带来诸多好处，让前后端攻城狮们顺畅了不少

SpringBoot集成Swagger2在线文档

后端给前端提供良好的接口文档是一种品质，也会减少彼此的沟通成本

SpringBoot集成Swagger2在线文档

这里推荐小伙伴们一款在线、实时更新接口文档工具，Swagger2，解放双手不是梦，谁用谁知道

集成SpringBoot

添加依赖

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

创建配置文件Swagger2Config.java

@Configuration
@EnableSwagger2
public class Swagger2Config {

     // 项目启动后，查看文档：http://{上下方路径}/swagger-ui.html
    // 如，http://localhost:8080/swagger-ui.html

    // Swagger2 核心配置 docket
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 指定api类型
                .apiInfo(createApiInfo())               //定义文档汇总信息
                .select().apis(RequestHandlerSelectors
                        .basePackage("cn.supergan.controller")) //指定controller包
                .paths(PathSelectors.any()) //所有controller
                .build();
    }

     // 构建文档信息
    public ApiInfo createApiInfo() {
        return new ApiInfoBuilder()
                .title("XXX 接口API")   //文档页标题
                .contact(new Contact("小动物不困", "https://www.supergan.cn", ""))   //联系人信息
                .description("XXX 接口API，实时更新，如有问题，及时沟通") //详细信息
                .version("1.0")   //文档版本号
                .termsOfServiceUrl("https://www.supergan.cn")    //网站地址
                .build();
    }
}

启动项目，访问文档首页http://localhost:8080/swagger-ui.html，效果如下

登录接口文档示例

代码

接口类：PassportController.java

@Api(tags = "登录")
@RestController
public class PassportController {

@ApiOperation(value = "登录", notes = "使用用户名和密码登录")
@ApiImplicitParams({
        @ApiImplicitParam(value = "用户名", name = "username", required = true),
        @ApiImplicitParam(value = "密码", name = "password", required = true)
})
@PostMapping("/login")
public JSONResult<Users> login(@RequestParam String username, @RequestParam String password) {
    Users users = new Users();
    // TODO 此处省略登录相关业务逻辑
    users.setUsername(username);
    users.setPassword(password);
    return JSONResult.ok(users);
}

用户类：Users.java

@ApiModel(description = "用户")
@Data
public class Users {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

响应类：JSONResult.java，统一接口的数据响应格式，小伙伴们可根据自己的需求改造和使用

@Data
public class JSONResult<T> {
    private Integer status;
    private String message;
    private T data;

    public JSONResult(ResultCode code) {
        this.setMessage(code.getMessage());
        this.setStatus(code.getStatus());
    }

    public static <T> JSONResult<T> ok(T data) {
        JSONResult<T> jsonResult = new JSONResult<T>(ResultCode.SUCCESS);
        jsonResult.setData(data);
        return jsonResult;
    }

    @Getter
    enum ResultCode {
        SUCCESS(200, "OK"),
        UN_KNOW_ERROR(500, "未知异常")
        ;
        private Integer status;
        private String message;

        ResultCode(Integer status, String message) {
            this.status = status;
            this.message = message;
        }
    }
}

效果

SpringBoot集成Swagger2在线文档

注解说明

@Api

@Api：用在请求的类上，说明该类的作用
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"
  
示例
@Api(tags="APP用户注册Controller")

@ApiOperation

@ApiOperation：用在请求的方法上，说明方法的作用
    value="说明方法的作用"
    notes="方法的备注说明"
  
示例
@ApiOperation(value = "登录", notes = "使用用户名和密码登录")

@ApiImplicitParams

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

示例
@ApiImplicitParams({
        @ApiImplicitParam(value = "用户名", name = "username", required = true),
        @ApiImplicitParam(value = "密码", name = "password", required = true)
})

@ApiResponses

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

示例
@ApiResponses({
    @ApiResponse(code=400,message="请求参数错误"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})

@ApiModel

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
  
示例
@ApiModel(description = "用户")
@Data
public class Users {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}