Swagger在线文档的使用
Swagger在线文档的使用
springboot整合Swagger2
1、首先创建一个springboot工程，在pom文件内导入依赖
<!--swagger依赖-->
io.springfox
springfox-swagger2
2.9.0
io.springfox
springfox-swagger-ui
2.9.0
2、在springboot工程内的项目运行无误后，创建配置类SwaggerConfig
@Configuration // 配置类
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
/**
* 配置了Swagger的Docket的Bean实例
* 可以有多个
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 获取项目环境
// 设置要显示的Swagger2环境
Profiles profiles = Profiles.of("dev");
// 监听 通过environment.acceptsProfiles判断是否处在自己设定的环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// Select a spec默认值
.groupName("茶碗儿")
// 是否开启swagger2
// .enable(false)
// 监听
.enable(flag)
.select()
// RequestHandlerSelectors 配置要扫描接口的方式
// basePackage 指定扫描的包
// any 扫描全部
// none 不扫描
// withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
// withMethodAnnotation 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.changgou.controller"))
// 过滤路径
// .paths(PathSelectors.ant("/changgou/**"))
.build();
}
@Bean
public Docket docket1(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("花生糖");
}
// 配置Swagger2信息
private ApiInfo apiInfo() {
// 作者信息
Contact contact = new Contact("茶碗儿", "https://www.cnblogs.com/chawaner/", "*******@qq.com");
return new ApiInfo(
// 大标题
"畅购商城",
// 描述
"畅购商城在线API",
// 版本
"v1.0",
// 服务组织url
"https://www.cnblogs.com/chawaner/",
// 作者信息
contact,
// 开源版本号
"Apache 2.0",
开源版本url
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
3、在JavaBean中加上注解
@ApiModel(description = "Result", value = "Result")
@Data // lombok注解
public class Result<T> implements Serializable {
@ApiModelProperty(value = "执行是否成功,true:成功,false:失败", required = true)
private boolean flag; // 是否成功
@ApiModelProperty(value = "返回状态码,20000:成功,20001:失败,20002:用户名或密码错误,20003:权限不足,20004:远程调用失败,20005:重复操作,20006:没有对应的抢购数据", required = true)
private Integer code; // 返回码
@ApiModelProperty(value = "提示信息", required = true)
private String message; // 返回消息
@ApiModelProperty(value = "逻辑数据", required = true)
private T data; // 返回数据
public Result(boolean flag, Integer code, String message, Object data) {
this.flag = flag;
this.code = code;
this.message = message;
this.data = (T) data;
}
public Result(boolean flag, Integer code, String message) {
this.flag = flag;
this.code = code;
this.message = message;
}
public Result() {
this.flag = true;
this.code = StatusCode.OK;
this.message = "操作成功!";
}
}
4、在controller类中加入注解
@Api(
value = "用户品牌操作",
tags = {"用户品牌操作接口"})
@RestController
@RequestMapping(value = "/brand")
@CrossOrigin // 跨域访问：域名、端口、协议不一致
public class BrandController {
@Autowired private BrandService brandService;
/** 查询所有 */
@ApiOperation("查询所有品牌信息")
@GetMapping
public Result<List<Brand>> findAll() {
// 查询所有品牌信息
List<Brand> brands = brandService.findAll();
// 响应结果封装
return new Result<List<Brand>>(true, StatusCode.OK, "查询品牌集合成功!", brands);
}
/** 根据主键id查询 */
@ApiOperation("据主键id查询") // 接口 放在方法上
@GetMapping(value = "/{id}")
public Result<Brand> findById(
@ApiParam(value = "传入的id") @PathVariable(value = "id") Integer id) {
Brand brand = brandService.findById(id);
return new Result<Brand>(true, StatusCode.OK, "根据id查询品牌成功!", brand);
}
/**
* 增加品牌
*
* @param brand
*/
@ApiOperation("增加品牌")
@PostMapping
public Result add(@ApiParam(value = "要增加的品牌信息") @RequestBody Brand brand) {
brandService.add(brand);
return new Result(true, StatusCode.OK, "添加品牌成功!");
}
/**
* 根据ID修改品牌数据
*
* @param id
* @param brand
* @return
*/
@ApiOperation("根据ID修改品牌信息")
@PutMapping(value = "/{id}")
public Result update(
@ApiParam(value = "输入的id", example = "1") @PathVariable(value = "id") Integer id,
@ApiParam(value = "brand") @RequestBody Brand brand) {
brand.setId(id);
brandService.update(brand);
return new Result(true, StatusCode.OK, "根据ID修改品牌成功!");
}
/**
* 根据ID删除品牌数据
*
* @param id
*/
@ApiOperation("根据ID删除品牌")
@DeleteMapping(value = "/{id}")
public Result delete(@ApiParam(value = "输入的id") @PathVariable(value = "id") Integer id) {
brandService.delete(id);
return new Result(true, StatusCode.OK, "根据ID删除品牌数据成功!");
}
/** 根据品牌信息多条件搜索 */
@ApiOperation("根据品牌信息多条件搜索")
@PostMapping(value = "/search")
public Result<List<Brand>> findList(@ApiParam(value = "查询条件") @RequestBody Brand brand) {
List<Brand> brands = brandService.findList(brand);
return new Result<List<Brand>>(true, StatusCode.OK, "根据品牌信息多条件搜索成功!", brands);
}
/**
* 分页查询实现
*
* @param page：当前页
* @param size：每页显示条数
* @return
*/
@ApiOperation("分页查询实现")
@GetMapping(value = "/search/{page}/{size}")
public Result<PageInfo<Brand>> findPage(
@ApiParam(value = "当前页") @PathVariable(value = "page") Integer page,
@ApiParam(value = "显示的条数") @PathVariable(value = "size") Integer size) {
PageInfo<Brand> pageInfo = brandService.findPage(page, size);
return new Result<PageInfo<Brand>>(true, StatusCode.OK, "分页查询成功!", pageInfo);
}
/**
* 分页查询 + 条件搜索
*
* @param brand:搜索条件
* @param page:当前页
* @param size:每页显示条数
* @return
*/
@ApiOperation("分页查询 + 条件搜索")
@PostMapping(value = "/search/{page}/{size}")
public Result<PageInfo<Brand>> findPage(
@ApiParam(value = "查询条件") @RequestBody Brand brand,
@ApiParam(value = "当前页") @PathVariable(value = "page") Integer page,
@ApiParam(value = "显示的条数") @PathVariable(value = "size") Integer size) {
PageInfo<Brand> pageInfo = brandService.findPage(brand, page, size);
return new Result<PageInfo<Brand>>(true, StatusCode.OK, "分页查询成功!", pageInfo);
}
}
5、配置文件application.yml中配端口号和端口扫描
注意：
1.端口号是从浏览器打开swagger-ui时的端口
2.配置端口扫描是为了设置在开发时开启swagger在线文档，在产品发布后不开启
3.注意看上面的SwaggerConfig配置类里面的：Profiles profiles = Profiles.of("dev");
扫描包含dev的配置文件，所以打开ui界面就得18082端口
application.yml
#端口的配置
server:
port: 18081
#设置对dev的端口开启swagger
#本来是访问http://localhost:18081/swagger-ui.html打开swagger-ui界面
#配置了这个之后，打开swagger-ui界面就要访问http://localhost:18082/swagger-ui.html
spring:
profiles:
active: dev
application-dev.yml
server:
port: 18082
application-pro.yml
server:
port: 18083
6、Swagger常用注解
| 位置 | 注解 | 说明 |
|---|---|---|
| controller | @Api | 对请求类的说明 |
| 方法 | @ApiOperation | 方法的说明 |
| 方法 | @ApiImplicitParams、@ApiImplicitParam | 方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明 |
| 方法 | @ApiResponses、@ApiResponse | 方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明 |
| 对象 | @ApiModel | 用在JavaBean类上，说明JavaBean的 用途 |
| 对象 | @ApiModelProperty | 用在JavaBean类的属性上面，说明此属性的的含议 |
@Api：
@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
示例
@Api(tags="订单模块")
@Controller
public class OrderController {
}
@Api其他属性配置：
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | 如, “application/json, application/xml” |
| consumes | 如, “application/json, application/xml” |
| protocols | 协议类型，如: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true ，将在文档中隐藏 |
@ApiOperation:
@ApiOperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
· query --> 请求参数的获取：@RequestParam
· header --> 请求参数的获取：@RequestHeader
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
示例：
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}
}
@ApiResponses、@ApiResponse：方法返回值的状态码说明
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
示例：
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}
@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述
@ApiModel的用途有2个：
当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。