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<PeopleVo> getPeoples(PeopleVo people) throws CommonException {
List<PeopleVo> 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