Swagger 接口管理框架

**简介：**swagger 可以用于自动生成接口文档并且可以对接口进行功能测试，能相当方便同步程序接口的修改，并且自动更新相应的文档，是一个相当不错的后端项目接口管理框架。

官网地址：地址

整合依赖：依赖地址

本文参考地址：地址，链接文档内部有ui切换，swagger的配置，安全权限管理等信息

默认配置流程：

创建配置类，并设置启用注解

@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
public class SwaggerConfig {
}

默认访问地址为：http://localhost:8080/swagger-ui.html，端口号是当前web项目的端口号，访问即可看到初始页面，但里面是空的。

可以在springboot的配置文件中修改应用根目录来更改默认访问地址。

配置接口

在项目的Controller层中开始配置，但要注意对于swagger来说，尽量不要使用@RequestMapping注解来接收请求，而要使用具体的请求方法去接收请求，否则swagger会对一个接口请求，产生多个不同方法的描述。

常用注解为：

@Api(tags = "角色管理") 
*//  定义API接口组，tags：你可以当作是这个组的名字，在类上定义。

@ApiOperation(value = "用户测试",notes = "用户测试notes") 
/*
*  该注解用于描述当前接口的信息。
*  value是接口的名称，notes是接口的描述，tags：可以额外定义接口组，让其他接口组也能显示此接口
*  此注解主要用在方法上
*/

**// 请求参数设置**
@ApiImplicitParams
// 声明多个请求参数时使用
@ApiImplicitParam
/* 单个请求参数的详细说明
* name:参数名称或字段名称，value：参数描述，required：参数是否必须，dataTypeClass：接收的实体类
* paramType：参数的类型，有path,query,body,form,header类型，表示传入参数的位置
* 用在方法上，特殊情况下可以用@ApiParam，可以在参数上使用。
/

**// 响应设置,响应时对非实体类只能设置响应码和相应的信息**
@ApiResponses
// 多个响应码时使用
@ApiResponse
// code:响应码，message：响应信息，在方法上使用*

请求参数为非实体类，响应也非实体类示例代码：

@Api(tags = "角色管理") //  当前接口组的名称。
@RestController
public class RoleController {
		@ApiOperation(value = "非实体类",notes = "非实体请求参数") // 接口信息描述
		*@ApiImplicitParams({
		@ApiImplicitParam(name = "username",  //参数名字
                    value = "用户名",   //参数的描述
                    required = true,   //是否必须传入
                    paramType = "query"  // 参数类型
                    )
		})
		@ApiResponses({
            @ApiResponse(code=200,message = "调用成功"),
            @ApiResponse(code=401,message = "无权限" )
    }
    )*
    @PostMapping("/test")
    public String test(String *username*){
        return "test";
    }
}

请求参数为实体类-响应也为实体类示例：

@Api(tags = "角色管理") //  当前接口组的名称。
@RestController
public class RoleController {
		@ApiOperation(value = "登录接口",notes = "登录接口的说明")
    @PostMapping("/login")
    public LoginForm login(@RequestBody LoginForm loginForm){ 
				// 会显示LoginForm对应实体类的信息，响应时也可以自动显示对应的信息。
        return loginForm;
    }
}

配置实体类

实体类在被controller层的接口调用时就会自动显示到swagger的接口文档中。

*@ApiModel(value="用户登录表单对象",description="用户登录表单对象")
// 用于标注实体类的信息，value：实体类名称，description：实体类说明
@ApiModelProperty(value="测试",required=true,example="root")
// 标注实体类中的字段信息，value：字段说明，required，是否必须，example：参数示例*