前后端分离开发,后端需要编写接⼝说明⽂档,会耗费⽐较多的时间。

swagger 是⼀个⽤于⽣成服务器接⼝的规范性⽂档,并且能够对接⼝进⾏测试的⼯具。

作用

  • ⽣成接⼝说明⽂档
  • 对接⼝进⾏测试

使用步骤

  1. 添加依赖

    <!--swagger-->
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    </dependency>
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
    </dependency>
  2. 写配置类 SwaggerConfig

    /**
    * SwaggerConfig 接口文档配置类
    */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig { /**
    * 配置接口文档生成规则
    */
    @Bean
    public Docket getDocket() {
    // 设置文档生成规则
    return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo()) // 设置文档信息
    .select()
    // 设置哪个包下的类需要生成文档
    .apis(RequestHandlerSelectors.basePackage("com.luis.fmmall.controller"))
    .paths(PathSelectors.any()) // 定义哪些路径的接口需要生成文档
    .build(); } /**
    * 设置文档信息
    */
    private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
    .title("xxx接口文档")
    .description("这里是相关描述")
    .version("1.0")
    .contact(new Contact("luis",
    "https://www.cnblogs.com/luisblog",
    "xxx@qq.com"))
    .build();
    }
    }
  3. 在控制器类上使用 Swagger 的注解进行相关说明

    示例如下:

    @RestController
    @RequestMapping("/user")
    @Api(tags = "用户管理", value = "提供用户的登陆、注册、修改等功能") //类说明
    public class UserController { @Resource
    private UserService userService; @GetMapping("/login")
    @ApiOperation(value = "登陆验证", notes = "用户登陆检查") //方法名说明
    @ApiImplicitParams({ //参数说明
    @ApiImplicitParam(dataType = "string", name = "username", value = "用户名", required = true),
    @ApiImplicitParam(dataType = "string", name = "password", value = "用户密码", required = false, defaultValue = "123")
    })
    public ResultVo login(@RequestParam("username") String name,
    @RequestParam(value = "password", defaultValue = "123") String pwd) {
    return userService.checkLogin(name, pwd);
    }
    }
  4. 启动 SpringBoot 应用,访问 http://localhost:8080/swagger-ui.html

    效果如下:

常用注解说明

  • @Api:类注解,使用在控制器类上,对类进行说明

    控制器类 UserController 示例:

    @Api(tags = "用户管理", value = "提供用户的登陆、注册、修改等功能") //类说明
    public class UserController {
    }
  • @ApiOperation:方法注解,使用在方法上,对方法名进行说明

  • @ApiImplicitParam@ApiImplicitParams:方法注解,使用在方法上,对方法的形参进行说明

    单个形参使用 @ApiImplicitParam,多个形参使用 @ApiImplicitParams

    控制器类 UserController 的 login 方法示例:

    @GetMapping("/login")
    @ApiOperation(value = "登陆验证", notes = "用户登陆检查") //方法名说明
    @ApiImplicitParams({ //参数说明
    @ApiImplicitParam(dataType = "string", name = "username", value = "用户名", required = true),
    @ApiImplicitParam(dataType = "string", name = "password", value = "用户密码", required = false, defaultValue = "123")
    })
    public ResultVo login(@RequestParam("username") String name,
    @RequestParam(value = "password", defaultValue = "123") String pwd) {
    return userService.checkLogin(name, pwd);
    }
  • @ApiModel @ApiModelProperty:当接⼝的形参或返回值为对象类型时,在实体类中添加此注解说明

    接口的返回值为 ResultVo 对象示例:

    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel(value = "ResultVo 对象", description = "返回给前端的封装数据") //返回的类说明
    public class ResultVo { // 响应给前端的状态码
    @ApiModelProperty("响应状态码") //属性说明
    private int code; // 响应给前端的提示信息
    @ApiModelProperty("提示信息") //属性说明
    private String msg; // 响应给前端的数据
    @ApiModelProperty("数据") //属性说明
    private Object data;
    }

    接口的形参为 User 实体对象示例:

    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel(value = "User 对象",description = "⽤户/买家信息")
    public class User {
    @ApiModelProperty(dataType = "int",required = false)
    private int userId;
    @ApiModelProperty(dataType = "String",required = true, value = "⽤
    户注册账号")
    private String userName;
    @ApiModelProperty(dataType = "String",required = true, value = "⽤
    户注册密码")
    private String userPwd;
    @ApiModelProperty(dataType = "String",required = true, value = "⽤
    户真实姓名")
    private String userRealname;
    @ApiModelProperty(dataType = "String",required = true, value = "⽤
    户头像url")
    private String userImg;
    }
  • @ApiIgnore:接⼝⽅法注解,添加此注解的⽅法将不会⽣成到接⼝⽂档中

swagger-ui 插件

发现一个规律,越学到最后,越是有惊喜,有不有?

swagger-ui 插件是一款 UI 美化插件,是基于 swagger 的。

之前使用的默认 swagger 文档和调试页面如果使用起来不太顺畅,可以试试这款 swagger-ui 插件。

使用

  1. 添加依赖

    <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
    </dependency>
  2. 重启 SpringBoot 应用,访问 http://localhost:8080/doc.html

    效果如下:

还等什么,赶紧装插件去~

Spring Boot 中使用 Swagger的更多相关文章

  1. Spring Boot中使用Swagger CodeGen生成REST client

    文章目录 什么是Open API规范定义文件呢? 生成Rest Client 在Spring Boot中使用 API Client 配置 使用Maven plugin 在线生成API Spring B ...

  2. spring boot 中使用swagger 来自动生成接口文档

    1.依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swa ...

  3. spring boot 中使用swagger

    一.pom.xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox ...

  4. 【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

    swagger提供开发者文档 ======================================================== 作用:想使用swagger的同学,一定是想用它来做前后台 ...

  5. Spring Boot中使用Swagger2构建强大的RESTful API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  6. Spring Boot中使用Swagger2构建API文档

    程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码 ...

  7. 在Spring Boot中使用swagger-bootstrap-ui

    在Spring Boot中使用swagger-bootstrap-ui swagger-bootstrap-ui是基于swagger接口api实现的一套UI,因swagger原生ui是上下结构的,在浏 ...

  8. Spring Boot中使用Swagger2构建RESTful APIs

    关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因: Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API. S ...

  9. Spring Boot中使用Swagger2自动构建API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

随机推荐

  1. [CSharpTips]判断两条线段是否相交

    判断两条线段是否相交 主要用到了通过向量积的正负判断两个向量位置关系 向量a×向量b(×为向量叉乘),若结果小于0,表示向量b在向量a的顺时针方向:若结果大于0,表示向量b在向量a的逆时针方向:若等于 ...

  2. java数组---概念

    1.数组的定义 数组是相同类型数据的有序集合.数组描述的是相同类型的若干个数据,按照一定的先后次序排列组合而成.其中,每一个数据称作一个数组元素,每个数组元素可以通过一个下标来访问它们. 2.数组的建 ...

  3. 痞子衡嵌入式:在i.MXRT启动头FDCB里使能串行NOR Flash的QPI/OPI模式

    大家好,我是痞子衡,是正经搞技术的痞子.今天痞子衡给大家介绍的是在FDCB里使能串行NOR Flash的QPI/OPI模式. 我们知道 Flash 读时序里有五大子序列 CMD + ADDR + MO ...

  4. SpringMVC 04: SpringMVC中4种页面跳转方式

    转发和重定向的页面跳转方式 页面跳转方式,本质上只有2种方式:转发 + 重定向 但在SpringMVC的具体实现上,转发可以细分为:普通的页面转发 + 经由action方法的页面转发 重定向可以细分为 ...

  5. Node.js躬行记(22)——Node环境升级日志

    公司之前所有的 Node 项目,其环境都是 8.9.4 版本,发布于 2018 年的一个比较古老的版本. 老版本有两个比较明显的问题: Node 高版本的特性和方法都无法使用. 有些第三方新版本的包无 ...

  6. flutter系列之:flutter中常用的GridView layout详解

    目录 简介 GridView详解 GridView的构造函数 GridView的使用 总结 简介 GridView是一个网格化的布局,如果在填充的过程中子组件超出了展示的范围的时候,那么GridVie ...

  7. js中new的原理

    面向对象 在了解new的原理之前,先简单地了解一下构造函数和对象. js可以通过构造函数创建对象: function Test() { } var t = new Test(); 构造函数的首字母大写 ...

  8. 最强cron解析器

    背景 大家有没有这么一种困境 我现在需要去配置一个定时任务:"每天早上九点执行任务" 若你有一个好的定时任务平台,相信很容易就能配置完成.那若是没有定时任务平台呢?是不是就要自己写 ...

  9. MySQL集群搭建(4)-MMM+LVS+Keepalived

    1 LVS 介绍 1.1 简介 LVS 是 Linux Virtual Server 的简写,意即 Linux 虚拟服务器,是一个虚拟的服务器集群系统.本项目在 1998 年 5 月由章文嵩博士成立, ...

  10. Qemu/Limbo/KVM镜像 Ubuntu 22.04 精简版,可运行Windows软件,内存占用不到200M

    镜像特征: Ubuntu 22.04系统 内置Wine 7.8,可运行大量Windows 软件 高度精简,内存占用仅200M不到. 自制UI,Windows3.1风格. 完全开源 镜像说明: 用户名为 ...