SpringBoot集成Swagger2在线文档

Posted supergan

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了SpringBoot集成Swagger2在线文档相关的知识,希望对你有一定的参考价值。

SpringBoot集成Swagger2在线文档

前言

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

技术图片

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

技术图片

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

集成SpringBoot

  1. 添加依赖

    <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>
  2. 创建配置文件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", "abc@email.com"))   //联系人信息
                    .description("XXX 接口API,实时更新,如有问题,及时沟通") //详细信息
                    .version("1.0")   //文档版本号
                    .termsOfServiceUrl("https://www.supergan.cn")    //网站地址
                    .build();
        }
    }
  3. 启动项目,访问文档首页http://localhost:8080/swagger-ui.html,效果如下
    技术图片

登录接口文档示例

代码

  1. 接口类: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);
    }
  2. 用户类:Users.java

    @ApiModel(description = "用户")
    @Data
    public class Users {
        @ApiModelProperty("用户名")
        private String username;
        @ApiModelProperty("密码")
        private String password;
    }
  3. 响应类: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;
            }
        }
    }

效果

技术图片

注解说明

@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;
}

总结

本文介绍了在SpringBoot中如何集成Swagger2,快速上手的用法,和主要注解的说明。

其中值得注意的是,上文中提到的JSONResult.java,它的泛型申明,在接口文档中起到了描述data属性详情的作用。

以上内容足以让你在日常开发中轻松驾驭Swagger2

以上是关于SpringBoot集成Swagger2在线文档的主要内容,如果未能解决你的问题,请参考以下文章

springboot系列(十七):集成在线接口文档Swagger2|超级详细,建议收藏

SpringBoot_springboot集成swagger2

第九节:SpringBoot在线文档Swagger2入门

springboot集成swagger2,构建优雅的Restful API

企业级 SpringBoot 教程 springboot集成swagger2,构建优雅的Restful API

SpringBoot整合Swagger2