先了解什么是RESTful API?
参考博文:https://blog.csdn.net/hjc1984117/article/details/77334616
总结:前后端分离,而双方需要一个联系中介。前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要。
Swagger就是一款让你更好的书写API文档的框架。
什么是Swagger?
如上,Swagger就是一款让你更好的书写API文档的框架,是一个Restful风格接口的文档在线自动生成和测试的框架 。 深入的了解和学习可以参考以下链接:
参考博文:https://blog.csdn.net/chenyulancn/article/details/79487318
https://blog.csdn.net/tuposky/article/details/77965139
官网地址:https://swagger.io/
下面以我的博文 搭建 SpringBoot 2.0 项目 (五) 搭建一个集成ssm的web项目 为基础,进行简单配置来入门swagger的设置与使用。
1、添加依赖
截止本博文发表日期,最新版本为 2.8.0。由于本人项目开发采用了2.7.0版本,本博文以 2.7.0 版本的为案例。
在pom.xml中插入相关依赖,自动下载。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、创建Swagger的配置文件
在启动类 Application 的同级目录下,创建配置文件
@Configuration
@EnableSwagger2
public class Swagger {
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("Swagger2 学习")
.description("RESTful API")
.contact(new Contact("Henry_Lin_Wind的博客", "https://blog.csdn.net/Henry_Lin_Wind", null))
.version("版本号:2.8.0")
.build())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}
}
启动项目,访问 http://localhost:8080/swagger-ui.html#/,即可看到如下页面。
从上图可看出,很多接口及其参数以及返回信息设置都没有相关的注释和说明。如下图所示,需要在相关位置加入注释。
接下来分步骤说明插入注释所需要的注解及其使用方法
3、添加接口说明
@ApiOperation :在Swagger中,默认以方法名作为API名称.可在方法上使用@ApiOperation来设置或修改名称
@ApiOperation("欢迎页面")
@RequestMapping(value = "/hello",method = RequestMethod.GET)
public String hello(){
System.out.println("Hello");
return "Log";
}
4、接口的相关参数的说明
@ApiImplicitParam:此注解可以设置接口下的 Parameters 的相关参数如Parameters 名称,描述,类型等。有多个参数可采用如下方式
@ApiImplicitParams({
@ApiImplicitParam
@ApiImplicitParam
})
参见下表,@ApiImplicitParam 有如下属性
属性 | 可选值 | 说明 |
---|---|---|
name | 参数名,例:@requestParams("a") String b ,则name=a | |
value | 参数说明 | |
dataType | 原始数据类型(string,int,long等)或class名 | 参数类型 |
paramType | query,path,body,header,form | 参数方式 |
required | true,false | 是否必填 |
allowMultiple | true,false | 允许多个值 |
defaultValue | 默认值 | |
allowableValues | 允许的值 | |
access |
属性详解如下:
- name : 参数名
必须与实际参数传入变量名一致.,显示在Parameters表格的Parameter列
- value : 参数说明
可任意填写,显示在Parameters表格的Description列
- paramType 参数方式,如下:
query : @RequestParam , @ModelAttribute
path : @PathVariable
body : @RequestBody
header: @RequestHeader
- required:是否必填- dataType:参数类型
可以是简单数据类型,如string,int,long等,也可以是一个类的类名,当dataType是一个自定义类时,参考Api自定义类说明
- 值为true或false.
当值为true时,Parameters表格的Parameter列与Description列为粗体,且value列的输入框显示required,该输入框为空时将阻止提交操作
- allowMultiple:允许多值
True或False
当为true时,输入框可使用”,”连接多个值,参数必须为数组或列表才可使用该属性
- defaultValue :默认值
该属性有值时,Parameters表格的value列输入框默认填入该值
- allowableValues :允许的值的数组
该属性有值时,Parameters表格的value列输入框将改为下拉列表,列表项为该值
以上属性了解后,开始在添加@ApiImplicitParam,设置相关属性:
@ApiOperation("用户登录")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query",name = "name", value = "用户名称", required = true, dataType = "String"),
@ApiImplicitParam(paramType="body",name = "password", value = "用户密码", required = true, dataType = "String")
})
@RequestMapping(value = "/login",method = RequestMethod.GET)
public String addUser1(String name,String password) {
设置完成后,刷新页面,可以看到相关属性已成功修改并更新。效果如下:
以上就是swagger的入门案例,附上2.8.0版本的swagger效果图。风格不同,按需使用。