文章目录
Swagger 的简介和使用
什么是Swagger
简介
wagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。
后端开发要为前端提供接口,同时还需要提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新,这个时候有可能会忘记更新接口的说明文档,造成一些不必要的问题。
归根到底,swagger就是帮助我们自动写接口说明文档的。更具体地,可以看下面的图片,swagger官方建议使用下面的红字部分。
Swagger页面
我们简单了解下,swagger的页面中各个元素的含义
Swagger快速上手
pom.xml文件中引入依赖
<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.8.0</version>
</dependency>
构建Swagger配置类
/**
* @auther Bachelor_HT
* @date 2023/6/23 14:43
* @desc default
*/
@Configuration
public class SwaggerConfigruationSettinngs {
//创建Docket对象
@Bean
public Docket docket() {
//1创建Docket对象
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//2创建Api信息, 接口文档的总体描述
ApiInfo apiInfo = new ApiInfoBuilder()
.title("动力节点金融项目")
.version("1.0")
.description("前后端分离的项目,前端Vue,后端Spring Boot + Dubbo分布式项目")
.build();
//3.设置使用ApiInfo
docket = docket.apiInfo(apiInfo);
//4.设置参与文档生成的包
docket = docket.select().apis(RequestHandlerSelectors.
basePackage("com.ht.front.controller")).build();
return docket;
}
}
补充说明:
- apiInfo:api基本信息的配置,信息会在api文档上显示,可有选择的填充,比如配置文档名称、项目版本号等
- apis:使用什么样的方式来扫描接口,RequestHandlerSelectors下共有五种方法可选。我们当前使用通过在类前添加@Api注解的方式,其他方法我们后续介绍。
- path:扫描接口的路径,PathSelectors下有四种方法,我们这里是全扫,其他方法我们后续介绍。
Swagger使用
常用注解说明
注解 | 说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
注解的使用
举一个简单的例子,涵括了以上大部分注解:
/**
* @auther Bachelor_HT
* @date 2023/6/26 0:52
* @desc default
*/
@Api(value = "用户功能")
@RestController
@RequestMapping("/v1/user")
public class UserController extends baseController {
@ApiOperation(value = "手机号注册")
@PostMapping("/register")
public RespResult userRegister(@RequestParam String phone,
@RequestParam String pword,
@RequestParam String smscode) {
return null;
}
}
执行上述代码,在输入http://localhost:8000/api/swagger-ui.html
,点击对应的接口,就可以看到:
总结
Swagger简单,易上手,是居家旅行必备良药。使用Swagger大大提升了我们的工作效率,加快开发进度,减少在开发时导致超出预期的概率,个人强烈建议!!!后续发一篇Swagger注解的详细说明。