目前，大多数公司都采用了前后端分离的开发模式，为了解决前后端人员的沟通问题，后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档，swagger2提供了强大的页面调试功能，这样可以有效解决前后端人员沟通难的问题。
下面我们使用SpringBoot结合swagger2生成Restful API文档。
一 搭建项目，引入依赖新建一个spring-boot-swaager的项目，引入swaager2的依赖，由于swagger2的ui不是很美观，这里将使用开源的swagger-bootstrap-ui做为ui。
引入依赖
io.springfoxspringfox-swagger22.9.2com.github.xiaoyminswagger-bootstrap-ui1.9.6
项目中配置swagger相关信息
@Configuration
@EnableSwagger2
public class configuration {
@Bean
public Docket createRestApi(){
return new Docket(documentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
// 标题
.title("某某项目接口文档")
// 描述
.description("swagger2接口文档使用演示")
// 版本
.version("1.0")
// 许可证
.license("MIT")
// 许可证地址
.licenseUrl("www.xx.com")
// 服务端地址
.termsOfServiceUrl("https://www.cnblogs.com/zhixie/")
// 联系信息
.contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","binzh303@163.com"))
.build();
}
}
访问路径，查看生成效果
文章中使用的这个ui，接口文档地址为ip:port/doc.html，生成的文档信息如下：
二 编写Restful接口新建实体类
@ApiModel("用户实体类")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
}
新建Restful接口
@Api(tags = "用户接口")
@RestController
@RequestMapping("person")
public class PersonController {
@ApiOperation(value = "获取用户列表",notes = "根据name获取用户列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true),
@ApiImplicitParam(name = "age",value = "年龄",dataType = "int",required = true)
})
@GetMapping("/{name}")
public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
return new Person(name,age);
}
@ApiOperation(value = "新增用户",notes = "根据用户实体类新增用户")
@ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
@PostMapping("add")
public int addPerson(@RequestBody Person person){
if(StringUtils.isEmpty(person)){
return -1;
}
return 1;
}
@ApiOperation(value = "更新用户信息",notes = "根据用户实体更新用户信息")
@ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
@PutMapping("update")
public int updatePerson(@RequestBody Person person){
if(StringUtils.isEmpty(person)){
return -1;
}
return 1;
}
@ApiOperation(value = "删除用户信息",notes = "根据用户名删除用户信息")
@ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true)
@DeleteMapping("/{name}")
public int deletePerson(@PathVariable(name = "name") String name){
if(StringUtils.isEmpty(name)){
return -1;
}
return 1;
}
}
我就直接用图来表示了，这样看着也更加直观
swagger2注解对应到文档上的表现形式如上。swagger2支持在线调试，打开某个具体的接口，根据提示填写对应的参数，点击发送就可返回响应结果。
此是spring-boot-route系列的第五篇文章，这个系列的文章都比较简单，主要目的就是为了帮助初次接触Spring Boot 的同学有一个系统的认识。本文已收录至我的github，欢迎各位小伙伴star！
github：https://github.com/binzh303/spring-boot-route
点关注、不迷路如果觉得文章不错，欢迎关注、点赞、收藏，你们的支持是我创作的动力，感谢大家。
如果文章写的有问题，请不要吝啬，欢迎留言指出，我会及时核查修改。
