Swagger入门指南-优快云博客

先了解什么是RESTful API？

参考博文：https://blog.youkuaiyun.com/hjc1984117/article/details/77334616

总结：前后端分离，而双方需要一个联系中介。前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要。

Swagger就是一款让你更好的书写API文档的框架。

什么是Swagger？

如上，Swagger就是一款让你更好的书写API文档的框架，是一个Restful风格接口的文档在线自动生成和测试的框架。深入的了解和学习可以参考以下链接：

参考博文：https://blog.youkuaiyun.com/chenyulancn/article/details/79487318

https://blog.youkuaiyun.com/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.youkuaiyun.com/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) {

设置完成后，刷新页面，可以看到相关属性已成功修改并更新。效果如下：