什么是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效果图。风格不同，按需使用。
