Swagger2
上次给大家推荐Swagger2这个神器，自动生成接口文档。不需要自己再专门写文档，对于程序员来说能提高工作效率。
但是上篇并没有讲怎么使用Wagger2这个软件，今天就带大家实现下。
环境
使用的语言是Java,其他语言也有类型的实现。官网链接:swagger2
框架是SpringBoot,构建工具是gradle.
实现
构建组件
在微服务开发中，我们会创建多个后端程序，在每个程序上都将swagger2的配置写一遍，显得很臃肿，我们这次在开发的时候将swagger2打造成一个组件的方式，后期直接引用。
新建立Gradle项目
// 增加依赖
dependencies {
compile("io.springfox:springfox-swagger2:2.9.1")
compile("io.springfox:springfox-swagger-ui:2.9.1")
compile("org.springframework.boot:spring-boot-autoconfigure:1.5.10.RELEASE")
compileOnly("org.springframework.data:spring-data-commons:1.12.6.RELEASE")
}
复制代码创建依赖的类
// 注意有些参数我们是通过配置文件配置过来的
@Configuration
@EnableSwagger2
public class Swagger2 {
@Resource
SwaggerProperties swaggerProperties;
/**
* 注入docket
* @return: Docket
* @author: fruiqi
* @date: 19-2-18 下午6:20
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(createApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePacakge()))
.paths(PathSelectors.any())
.build();
}
/**
* 创建api
* @return: springfox.documentation.service.ApiInfo
* @author: fruiqi
* @date: 19-2-18 下午6:20
*/
private ApiInfo createApiInfo(){
return new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.version(swaggerProperties.getVersion())
.build();
}
}
复制代码读取配置文件的类
@Configuration
public class SwaggerProperties {
/**
* 标题 默认
*/
@Value("${swagger.title}")
private String title = "标题";
/**
* 描述
*/
@Value("${swagger.description}")
private String description = "描述";
/**
* 版本号
*/
@Value("${swagger.version}")
private String version = "1.0.0";
/**
* 包路径信息
*/
@Value("${swagger.basepackage}")
private String basePacakge = "com.infervision";
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
public String getDescription() {
return description;
}
public void setDescription(String description) {
this.description = description;
}
public String getVersion() {
return version;
}
public void setVersion(String version) {
this.version = version;
}
public String getBasePacakge() {
return basePacakge;
}
public void setBasePacakge(String basePacakge) {
this.basePacakge = basePacakge;
}
}
复制代码我们的文件属性放到配置文件中，作为组件内容引入到别的项目中，配置文件类中使用的属性从其他项目配置文件获取。
其他项目引入上面的wagger组件，组件的项目名称
compile project(':swagger-manage')
//配置文件如下
swagger:
title: test
description: 开发devapi
version: 1.0.0
basepackage: com.infervision
复制代码我们在其他项目可以随意引入该组件，但更好的引入方式可以将其打成mavenjar包，放到maven仓库中，以后可以使用maven的方式调用自己生成的swagger组件。
使用
创建Controller类，使用不同的注解标识我们创建的接口。
@RestController
@RequestMapping("people")
@Api(value = "people", description = "用户控制端")
public class PeopleController {
/**
* 日志
*/
private static final Logger logger = LoggerFactory.getLogger(PeopleController.class);
@Autowired
PeopleService peopleService;
/**
* 根据用户实体内容 分类查询用户
* 1. 在这里 vo层将查询条件封装成为一个实体或者
* 参数较少可以直接使用RESTful的方式将其传参
* @param people 用户实体
* @return: com.infervision.model.People
* @author: fruiqi
* @date: 19-2-20 上午10:45
*/
@GetMapping
@ApiOperation(value = "获取用户列表信息", notes = "条件可以选择 用户名,公司等内容")
public List getPeoples(PeopleVo people) throws CommonException {
List peoples = peopleService.getPeoples(people);
return peoples;
}
/**
* 增加用户信息
*
* @param peopleVo 增加的用户信息
* @return: com.infervision.model.PeopleVo
* @author: fruiqi
* @date: 19-2-20 下午3:31
*/
@PostMapping
@ApiOperation(value = "增加用户")
public PeopleVo addPeople(@RequestBody PeopleVo peopleVo) {
PeopleVo result = peopleService.addPeople(peopleVo);
return result;
}
/**
* 修改对象
* @param id 用户id
* @param peopleVo 修改的对象
* @return: com.infervision.model.PeopleVo
* @author: fruiqi
* @date: 19-2-20 下午4:06
*/
@PutMapping("{id}")
@ApiOperation(value="更新用户")
@ApiImplicitParams({
@ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true)
})
public PeopleVo updatePeople(@PathVariable Integer id, @RequestBody PeopleVo peopleVo) {
PeopleVo result = peopleService.updatePeople(id, peopleVo);
return result;
}
@DeleteMapping("{id}")
@ApiOperation(value="删除用户")
@ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true)
public void deletePeople(@PathVariable Integer id){
if (id != null){
peopleService.deletePeople(id);
logger.info("[INFO] 删除用户id ");
}
}
}
复制代码 成功示意图
总结
上面的实现方式我们就打造成一个wagger2的组件了，后期我们在使用就可以直接引入项目。
源码地址：https://github.com/menhuan/notes/tree/master/code/codebase-master/swagger-manage
可以直接获取组件内容。
后缀内容
·END·
路虽远，行则必至
本文原发于 同名微信公众号「胖琪的升级之路」，回复「1024」你懂得，给个赞呗。
微信ID：YoungRUIQ