Swagger配置整理

Swagger配置说明

boot项目启动类上需要加上

@EnableSwagger2

开启SpringBoot自动注入，注入Swagger

@Component
@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Value(value = "${swagger.enable}")
	private boolean enable;

	@Bean
	public Docket createRestApiXyg() {
		return new Docket(DocumentationType.SWAGGER_2).
            	//调用下面的apiInfoXyg方法
apiInfo(apiInfoXyg()).enable(enable).select().apis(RequestHandlerSelectors.any())
            	//自己的controller类上的接口地址
				.paths( PathSelectors.ant("/xy/**")).build()
				.securityContexts(Arrays.asList(securityContexts()))
                .securitySchemes(Arrays.asList(securitySchemes()))
            	//名称不能重复
                .groupName("新员工")
				.pathMapping("/");
	}

	private ApiInfo apiInfoXyg() {
        //设置名称
		return new ApiInfoBuilder().title("员工职业发展-业绩积分").description("新员工API").version("1.0").build();
	}

Swagger 的注解

@Api

@Api: 用在请求的类上，表示对类的说明

• tags 说明该类的作用，可以在前台界面上看到的注解
• value 该参数无意义，在UI界面上看不到，不需要配置

@Api(tags = "用户接口")
public class UserController{
    //...接口内容
}

@ApiOperation

• 使用于在方法上，表示一个http请求的操作

• @ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response =
  “接口返回参数类型”, notes = “接口发布说明”)

  • value：对该操作进行简单的描述，尽量控制在120字符以内。
  • notes：对操作的详细描述。
  • httpMethod：指定操作使用的HTTP方法类型，可选值 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH。
  • tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。（就是分组）

@ApiOperation(value = "验证 @ApiOperation 注解",
        notes = "验证 @ApiOperation 注解 value 和 notes 属性的用法",
        httpMethod = "POST")
@RequestMapping("/demo1")
public void demo1() {
    //...
}

@ApiImplicitParam

作用在方法上，用于设置单个请求参数，用法示例

@PutMapping("/update")
@ApiOperation(value = "更新用户信息", notes = "根据用户登录token更新客户端提交的用户资料")
public Object update() {
    Map<String,Object> map = new HashMap<>();
    map.put("list", null);
    return map;
}

@ApiImplicitParams

作用在方法上，用于包含多个 @ApiImplicitParam，

• name ：参数名。
• value ： 参数的具体意义，作用。
• required ： 参数是否必填。
• dataType ：参数的数据类型。
• paramType ：查询参数类型，这里有几种形式：
  • path 以地址的形式提交数据
  • query 直接跟参数完成自动映射赋值
  • body 以流的形式提交 仅支持POST
  • header 参数在request headers 里边提交
  • form 以form表单的形式提交 仅支持POST

用法示例：

@PostMapping("/register")
@ApiOperation(value = "用户注册", notes = "APP用户注册")
@ApiImplicitParams({
        @ApiImplicitParam(name = "mobile", value = "手机号码", dataType = "string", paramType = "query", example = "13802780104", required = true),
        @ApiImplicitParam(name = "user_name", value = "登录账号", dataType = "string", paramType = "query", example = "lihailin9073", required = true),
        @ApiImplicitParam(name = "password", value = "登录密码", dataType = "string", paramType = "query", example = "123456", required = true),
        @ApiImplicitParam(name = "validate_code", value = "注册验证码", dataType = "string", paramType = "query", example = "3679", required = true)
})
public Object create() {
    Map<String,Object> map = new HashMap<>();
    map.put("list", null);
    return map;
}

@ApiParam

可以作用在接口方法上面，以及接口方法中的参数位置的注解，其主要是用来给接口中的参数定义相关参数说明：带颜色的是常用的，注意这三个就好了

属性名称	属性类型	默认值	作用
name	Strig	空	定义参数名称
value	String	空	定义参数简单描述
required	boolean	false	定义参数传递必要性
allowableValues	String	空	定义参数取值范围
defaultValue	String	空	定义参数默认值
access	String	空	定义参数访问规则
allowMultiple	boolean	false	定义参数能否接收多个数值
example	String	空	定义参数单个示例
hidden	boolean	false	定义参数显隐

示列：

@RequestMapping(value = "/toExportAndDmsPartList", method = RequestMethod.POST)
    @ApiOperation(value = "出口及DMS配件关系", notes = "出口及DMS配件关系")
    public ResultData<PageInfo<ExportAndDmsPartDTO>> toExportAndDmsPartList(@ApiParam(name = "exportAndDmsPartDTO", value = "出口及DMS配件关系DTO", required = true) @RequestBody ExportAndDmsPartDTO exportAndDmsPartDTO) {
        return ResultData.success(exportAndDmsPartService.toExportAndDmsPartList(exportAndDmsPartDTO));
    }

@ApiModel

在实体类上边使用，标记类是swagger的解析类

属性名称	数据类型	默认值	说明
value	String	类名	为模型提供备用名称
description	String	“”	提供详细的描述
parent		void.class	为模型提供父类以允许描述继承关系
discriminatory	String	“”	支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes		{}	从此模型继承的子类型数组
reference	String	“”	指定对应类型定义的引用，覆盖指定的任何其他元数据

示例：

@Data
@ApiModel(value = "出口配件表DTO", description = "出口配件表")
public class ExportAndDmsPartDTO {
	private String name;
}

@ApiModelProperty

使用在被 @ApiModel 注解的模型类的属性上

属性名称	数据类型	默认值	说明
value	String	“”	属性简要说明
name	String	“”	运行覆盖属性的名称。重写属性名称
required	boolean	“”	是否为必传参数,false:非必传参数; true:必传参数
example	String	“”	属性的示例值
allowableValues	String	“”	限制此参数的可接受值
access	String	“”	允许从API文档中筛选属性
notes	String	“”	当前未使用
dataType	String	“”	参数的数据类型
position	int	0	允许对模型中的属性进行显式排序
hidden	boolean	false	允许在Swagger模型定义中隐藏模型属性
readOnly	boolean	false	允许将模型属性指定为只读
reference	String	“”	指定对相应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue	boolean	false	允许传递空值

示例：

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "SysUserInfoResponse", description = "用户信息响应模型")
public class SysUserInfoResponse {
	
	@ApiModelProperty(value = "用户ID", required = true, example = "")
	private String userId;
 
	@ApiModelProperty(value = "用户名", required = false, example = "")
	private String userName;
 
	@ApiModelProperty(value = "所属部门Id", required = false, example = "")
	private String deptId;
	
	@ApiModelProperty(value = "所属公司", required = false, example = "")
	private String comId;
 
	@ApiModelProperty(value = "所属公司名称", required = false, example = "")
	private String comName;
	 
	@ApiModelProperty(value = "身份证号", required = false, example = "")
	private String idnum;
 
	@ApiModelProperty(value = "手机号", required = false, example = "")
	private String phone;
 
	@ApiModelProperty(value = "邮箱", required = false, example = "")
	private String email;
}

@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明

两者关联使用;@ApiResponse参数如下

属性	类型	说明
code	int	数字，例如400
message	String	信息，例如"请求参数没填好"
response	Class<?>	抛出异常的类

示例：

@ApiResponses({
		@ApiResponse(code = 200, message = "请求成功"),
		@ApiResponse(code = 400, message = "请求参数没填好"),
		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
	}) 
@ResponseBody
@RequestMapping("/user")
public ApiResult getUser(@RequestParam String userId) {
    ...
}

其他相关资料，请查询相关文档。