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) {
...
}
其他相关资料,请查询相关文档。