Swagger2接口文档
你还在为写接口word文档而头痛烦恼吗?你还在与前端苦苦说明api作用而口干舌燥吗?你还在为给领导视察任务量而心跳不安吗?那就赶紧将Swagger2学起来,妈妈再也不用担心了。而你也不用为写大量word文档而掉头发,同时还提供了直接调试接口的方法,而且学起来十分简单上手,我们赶紧学习今天新的一点点知识。
Swagger2其实就是Swagger2.0版本,所以本质上就是Swagger。首先第一步当然是导入依赖:
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
依赖版本我选择的是2.4.0,大家也可以选择其他版本,Swagger2无需在配置文件中进行配置编写,而是直接编写配置类即可:
/**
* swagger2的配置类
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* swagger2配置文件,这里可以配置swagger2的基本内容
* 主要是配置要扫描的接口的包
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//扫描的包不同项目设置不同
.apis(RequestHandlerSelectors.basePackage("com.xie.example.controller"))
.paths(PathSelectors.any())
.build();
}
/**
*构建api文档的信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//设置页面标题
.title("使用swagger构建springboot的api文档")
//设置联系人
.contact(new Contact("nanshenjiang","https://blog.csdn.net/nanshenjiang",""))
//描述
.description("swagger2示例演示")
//服务网址
//.termsOfServiceUrl("https://blog.csdn.net/nanshenjiang")
//版本号
.version("1.0")
.build();
}
}
其中配置类中要实现两个方法,createRestApi()方法中主要是注意扫描的包的不同,它扫描的是controller层的包,将其中的api接口扫描进去即可。而apiInfo()方法中主要说明的是构建成功后的文档内的信息(可看下图),根据每个人需求不同而修改。
然后就是相关注解与接口的结合使得文档丰富起来,我会通过代码与注解同时说明其作用,首先说明的是已完成的controller层,我们直接在controller层上添加注解:
@RestController
@RequestMapping("/user")
@Api(value = "对用户操作的接口",tags = "对用户操作的controller")
public class UserController {
@Autowired
private UserService userService;
/**
* 查询所有用户
*/
@ApiOperation(value = "查询全部用户",notes = "查询全部用户的接口")
@GetMapping("/list")
public List<User> list(Model model) {
return userService.findAll();
}
/**
* 根据 id 查询用户
*/
@GetMapping("/{id}")
@ApiOperation(value = "根据用户id查询用户",notes = "根据id查询用户的接口")
@ApiImplicitParam(name = "id",value = "用户id",required = true, dataType = "Integer", paramType = "path")
public User findUser(@PathVariable("id") Integer id){
return userService.findById(id);
}
/**
* 保存用户
*/
@PostMapping
@ApiOperation(value = "创建用户",notes = "创建用户的接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "用户名",required = true, dataType = "String",paramType = "query"),
@ApiImplicitParam(name = "age",value = "年龄",required = true, dataType = "Integer",paramType = "query"),
@ApiImplicitParam(name = "email",value = "邮箱",required = true, dataType = "String",paramType = "query")
})
public void saveUser(@RequestParam("name") String name,
@RequestParam("age") Integer age,
@RequestParam("email") String email){
User user=new User();
user.setName(name);
user.setAge(age);
user.setEmail(email);
userService.saveOrUpdateUser(user);
}
/**
* 修改用户
*/
@ApiOperation(value = "修改用户",notes = "修改用户的接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户名id",required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "name",value = "用户名",required = true, dataType = "String",paramType = "query"),
@ApiImplicitParam(name = "age",value = "年龄",required = true, dataType = "Integer",paramType = "query"),
@ApiImplicitParam(name = "email",value = "邮箱",required = true, dataType = "String",paramType = "query")
})
@PutMapping("/{id}")
public void updateUser(@PathVariable("id") Integer id,
@RequestParam("name") String name,
@RequestParam("age") Integer age,
@RequestParam("email") String email){
User user=new User();
user=userService.findById(id);
if(name!=null||!name.isEmpty()){
user.setName(name);
}
if(email!=null||!email.isEmpty()){
user.setEmail(email);
}
if(age!=null){
user.setAge(age);
}
userService.saveOrUpdateUser(user);
}
/**
* 删除用户
*/
@ApiOperation(value = "删除用户",notes = "删除用户的接口")
@ApiImplicitParam(name = "id",value = "用户id",required = true, dataType = "Integer", paramType = "path")
@DeleteMapping("/{id}")
public void deleteUser(@PathVariable("id") Integer id){
userService.deleteById(id);
}
/**
* 根据用户名查询用户
*/
@ApiIgnore
@GetMapping("/findbyname")
public User findUser(@RequestParam("name") String name){
return userService.findByName(name);
}
}
其中service层是已经设置好的(mapper层和service层的编写并不影响接口文档本身),我们即在上面编写即可,而其中涉及的注解有:
(1)@Api:用在请求的类上,说明该类作用
- tags:说明该类的作用,可以在接口文档中直接看到
- value:该参数无啥意义
(2)@ApiOperation:用在请求的方法上,说明方法的作用
- value:说明方法的用途、作用
- notes:方法的备注说明
(3)@ApiImplicitParam:用在请求方法上,指定一个该方法请求参数的各个方面
- name:参数名
- value:对参数名进行说明和解释
- required:参数是否必须传
- dataType:说明参数类型
- paramType:指定参数存放位置,其中分为:
- header:请求参数放置于Request Header,使用@RequestHeader获取
- query:请求参数放置于请求地址,使用@RequestParam获取
- path:用于restful接口,目的是请求参数的获取,即@PathVariable
- body:(不常用)
- form(不常用)
(4)@ApiImplicitParams:用在请求的方法上,表示一组参数说明(将多个@ApiImplicitParam封装说明)
(5)@ApiIgnore:用在请求方法上,忽视该接口,则该接口不会在文档上显示
而在entity(或称为pojo)实体类中,我们还会使用以下注解进行说明:
@Entity
@Table(name = "user")
@ApiModel(value = "用户对象",description = "这是一个用户对象")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@ApiModelProperty(hidden = true)
private Integer id;
@Column(nullable = false,length = 50)
@ApiModelProperty(value = "用户名",name = "name",example = "姓名",required = true)
private String name;
@Column(nullable = false)
@ApiModelProperty(value = "岁数",name = "age",example = "18",required = true)
private Integer age;
@Column(nullable = false,length = 50)
@ApiModelProperty(value = "邮箱",name = "email",example = "xxx@xx.com",required = true)
private String email;
//省略了构造函数和getset函数
}
在model类上进行注解则我们在查阅文档时会对该类进行说明,其中涉及的注解有:
(1)@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
- value:说明model
- description:详细描述该model
(2)@ApiModelProperty:用于model类中属性的说明,描述该model中的属性上
- name:该属性名
- value:对参数名进行说明和解释
- example:举一个该属性例子
- required:是否必须
另外,有一些注解我并无用到,这里也说明一下:
(1)@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- code:数字,例如400
- message:信息,例如"请求参数没填好"
- response:抛出异常的类
(2)@ApiResponses:用在请求的方法上,表示一组响应
然后我们运行程序,访问:http://localhost:8080/swagger-ui.html即可
我们来看看运行后文档的效果:
获取全部用户接口:
在进行try it out!后即可获取数据库中所有user的数据:
根据用户id查询用户的接口:
同理,通过输入id后即可查询。删除用户接口与之相似,只是对输入id的用户进行删除。
而创建用户和修改用户区别也不大:
输入后try it out即可,它也会将返回的参数进行打印,由于我没做参数类,所以也不显示了,大伙自己去尝试
遇到的问题:
(1)代码没问题,但是文档接口中api接口无法点击,又或者说直接没有接口显示:
解决:我在360浏览器调试时就会出现这样子的问题。大伙还是去chrome谷歌浏览器访问该网站,在谷歌浏览器就不会出现这样子的问题