OpenAPI规范(OpenAPI Specification简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程。Swagger是目前最瘦欢迎的OpenAPI规范API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。
Swagger可以随项目生成强大的RESTful API文档,减少开发人员的工作量(不用自己写API接口文档了)。使用Swagger,只需要在代码中添加一些注解即可生成API接口文档,便于同步更新API文档的说明。另外生成API文档页面带有测试功能,可以用来调试每个RESTful API接口。
2020.07出了Swagger3.0,但是目前文档和网上教程都不太完善,后续学有余力再研究一下3.0,具体的资料都在官方github。
Swagger 2.x基本使用
3.0已经有starter了,导一个就可以,但是2.9.2还需要导两个依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
然后需要一个配置类,用来配置一些基本信息,格式基本是固定的:
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//扫描带有ApiOperation注解的方法
.paths(PathSelectors.any())
.build();
}
// 创建api的基本信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("用户账号接口文档")
.description("集成Swagger2构建Restful APIS")
.termsOfServiceUrl("http://www.xxxxx.com/")
.contact(new Contact("youkee", "", "xdutao@foxmail.com"))
.license("采用 Apache 2.0开源许可证")
.version("1.0.0")
.build();
}
}
这么看可能有点一头雾水,但是现在只配置这一点东西,然后打开http://localhost:8080/swagger-ui.html,看一下页面上的内容,就大概知道了:
等于说这个配置类在配接口文档页面的基本信息和一些扫描规则。
下面写一个简单的pojo User和UserController
@Data
public class User {
private Integer id;
private String name;
}
@Controller
public class UserController {
private Integer count = 1000;
@GetMapping("/users")
public ModelAndView getUserCount() {
ModelAndView modelAndView = new ModelAndView();
modelAndView.addObject("userCount", count);
modelAndView.setViewName("userCount");
return modelAndView;
}
@GetMapping("/users/{id}")
public @ResponseBody User getUserById(@PathVariable("id") Integer id) {
User user = new User();
user.setId(id);
user.setName("bob" + id);
return user;
}
@PostMapping("/users/{id}/{name}")
public ModelAndView insertUser(@PathVariable("id") Integer id,
@PathVariable("name") String name) {
ModelAndView modelAndView = new ModelAndView();
User user = new User();
user.setId(id);
user.setName(name);
modelAndView.addObject("user", user);
count++;
modelAndView.addObject("userCount", count);
modelAndView.setViewName("insertSuccess");
return modelAndView;
}
}
但是在没有任何注解的情况下,Swagger是没办法帮你生成这些方法的接口文档的,下面先列举一些注释的用途,然后再结合代码看一下具体的作用。列举的注解和属性都不是特别全的,可以点进源码看一下,代码的注释都说的非常清楚;或者看官网文档,不过官方文档也已经更新成3.0的用法了,后续再好好学一下。
-
@Api:用在类上,说明该类的作用
-
@ApiOperation:用在方法上,说明方法的作用
-
@ApiImplicitParams:用在方法上包含一组参数说明
-
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
-
paramType:参数放在哪个地方
- header --> 请求参数的获取@RequestHeader
- query --> 请求参数的获取@RequstParam
- path --> 请求参数的获取@PathVariable
- body --> 请求参数的获取@RequestBody
- form --> form-data获取参数
-
name:参数名
-
dataType:参数类型
-
required:参数是否必须传
-
value:参数的意思
-
defaultValue:参数的默认值
-
-
@ApiResponses:用于表示一组响应
-
@ApiResponse:用在@ApiResponses注解中,用于表达一个错误的响应信息
- code:数字,比如400,404
- message:信息,例如“请求参数不合法”
- response:抛出异常的类
-
@ApiIgnore:使用该注解忽略这个API,不在页面上显示
-
@ApiModel:描述一个Model的信息
-
@ApiModel:描述一个Model的属性
先对User改造一下:
@Data
@ApiModel(value = "User", description = "用户对象")
public class User {
@ApiModelProperty(value = "用户ID", example = "1001")
private Integer id;
@ApiModelProperty(value = "用户姓名", example = "张三")
private String name;
}
然后controller的代码是改动最多的,需要加很多注解:
@Controller
@Api(tags = "用户控制层,负责处理用户相关请求")
public class UserController {
private Integer count = 1000;
@ApiOperation(value = "获取用户总人数", notes = "查询数据库中所有用户")
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 401, message = "请求路径没有相应权限"),
@ApiResponse(code = 403, message = "请求路径呗隐藏,不能访问"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
@ApiResponse(code = 405, message = "请求方法不支持")
})
@GetMapping("/users")
public ModelAndView getUserCount() {
ModelAndView modelAndView = new ModelAndView();
modelAndView.addObject("userCount", count);
modelAndView.setViewName("userCount");
return modelAndView;
}
@ApiOperation(value = "查询用户", notes = "根据路径中的id在数据库中查询用户")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", dataType = "Integer")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "缺少必要的请求参数"),
@ApiResponse(code = 401, message = "请求路径没有相应权限"),
@ApiResponse(code = 403, message = "请求路径被隐藏,不能访问"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
@ApiResponse(code = 405, message = "请求方法不支持")
})
@GetMapping("/users/{id}")
public @ResponseBody User getUserById(@PathVariable("id") Integer id) {
User user = new User();
user.setId(id);
user.setName("bob" + id);
return user;
}
@ApiOperation(value = "插入用户", notes = "根据路径中的id,name创建用户并插入数据库")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", dataType = "Integer"),
@ApiImplicitParam(paramType = "path", name = "name", value = "用户姓名", dataType = "String")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "缺少必要的请求参数"),
@ApiResponse(code = 401, message = "请求路径没有相应权限"),
@ApiResponse(code = 403, message = "请求路径被隐藏,不能访问"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
@ApiResponse(code = 405, message = "请求方法不支持")
})
@PostMapping("/users/{id}/{name}")
public ModelAndView insertUser(@PathVariable("id") Integer id,
@PathVariable("name") String name) {
ModelAndView modelAndView = new ModelAndView();
User user = new User();
user.setId(id);
user.setName(name);
modelAndView.addObject("user", user);
count++;
modelAndView.addObject("userCount", count);
modelAndView.setViewName("insertSuccess");
return modelAndView;
}
}
看着比较多,但是对应着生成的接口文档看一下,就比较清晰了:
剩下的ModelAndView是因为返回方法中返回的有,所以也当Model处理了,没有@ApiModel注解,所以内容也比较乱。