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在线文档的更多相关文章

  1. springboot使用swagger2创建文档

    一.导入swagger2依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>spri ...

  2. SpringCloud微服务实战——搭建企业级开发框架(六):使用knife4j集成Swagger2接口文档

    knife4j是为集成Swagger生成api文档的增强解决方案,前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活, 提供专注于Swagger的增强解决方案,不同于只是改善增强前 ...

  3. springboot集成restdocs输出接口文档

    1.pom文件新增restdocs <dependency>    <groupId>org.springframework.restdocs</groupId> ...

  4. SpringBoot整合Swagger2搭建API在线文档

    Swagger,中文"拽"的意思,它是一个功能强大的在线API在线文档,目前它的版本为2.x,所以称为Swagger2.Swagger2提供了在线文档的查阅和测试功能.利用Swag ...

  5. springboot集成swagger2构建RESTful API文档

    在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...

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

    swagger,中文“拽”的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅 ...

  7. (转)第十一篇:springboot集成swagger2,构建优雅的Restful API

    声明:本部分内容均转自于方志明博友的博客,因为本人很喜欢他的博客,所以一直在学习,转载仅是记录和分享,若也有喜欢的人的话,可以去他的博客首页看:http://blog.csdn.net/forezp/ ...

  8. (转) SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API

    swagger,中文“拽”的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅 ...

  9. SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API

    转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot-swagger2/ 本文出自方志朋的博客 swa ...

随机推荐

  1. vue 学习 渲染、v-指令

    vue渲染 在组件中data是一个方法里面的值要是一个对象return出去 export default { name: "HelloWorld", data() { return ...

  2. html学习笔记--xdd

    <!DOCTYPE html> <html> <head> <title>HTML学习笔记</title> <meta charset ...

  3. find_all的用法 Python(bs4,BeautifulSoup)

    find_all()简单说明: find_all() find_all() 方法搜索当前tag的所有tag子节点,并判断是否符合过滤器的条件 用法一: rs=soup.find_all('a') 将返 ...

  4. Mysql查询语句之排序查询

    语法: /* select 查询列表 from 表 [where 筛选条件] order by 排序列表 [asc/desc] */ ①asc为升序,desc为降序,且默认为升序 ②order by子 ...

  5. C#笔记01——注释、进制、基本数据类型、量和输入输出函数

    一.注释 1.单行注释 使用方法:行首加 ” //“: VS2019中的快捷键(以后如果不特加说明都是VS2019): 注释(CTRL+E,C): 取消注释(CTRL+E,U): 2.多行注释 使用方 ...

  6. 经典算法之K近邻(回归部分)

    1.算法原理 1.分类和回归 分类模型和回归模型本质一样,分类模型是将回归模型的输出离散化. 一般来说,回归问题通常是用来预测一个值,如预测房价.未来的天气情况等等,例如一个产品的实际价格为500元, ...

  7. scrapy下载中间件结合selenium抓取全国空气质量检测数据

    1.所需知识补充 1.下载中间件常用函数 process_request(self, request, spider): 当每个request通过下载中间件是,该方法被调用 process_reque ...

  8. AI手写输入法 - pytorch从入门到入道(二)

    本章承接上一篇的手写数字识别,利用训练好的模型,结合pyqt画板,实现简易手写输入法,为"hello world"例子增添乐趣. pyqt是开发图形界面的框架,可以百度查找相关资料 ...

  9. c堆排序

    #include<stdio.h> #include<stdlib.h> /* p是循环输出的下表*/ ; /*堆调整算法*/ /* r[]数组 , 根结点的编号为k,最后一个 ...

  10. input 输入框 只能输入数字、字母、汉字等

    1.文本框只能输入数字代码(小数点也不能输入) <input onkeyup="this.value=this.value.replace(/\D/g,'')" onafte ...