1 爲何是使用swagger?html
1-1 當後臺開發人員開發好接口,是否是還要從新書寫一份接口文檔提給前端人員,固然對於程序員最不喜歡的就是書寫文檔(固然文檔是必須的,有利於項目的維護)前端
1-2 當後臺人員開發接口,固然後臺開發者也是須要測試好接口是否可用,當參數少的時候測試還不是很麻煩,當參數有十多個的時候,就須要後臺開發者一個一個的拼接參數,非常耗時間並且還容易寫錯參數名,swagger就很好解決了這個問題(固然也是能夠藉助其餘插件:rest-client工具,PostMan)git
2 搭建環境:window,spring boot,swaager,maven程序員
3 開始搭建:搭建過程很簡單,有關於swagger註解本文不詳細敘述,其實只使用經常使用的幾個註解就ok了(@ApiOperation,@EnableSwagger2,@Api)github
3-1 導入必須jar包 ,修改pom.xml web
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>RELEASE</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-aop</artifactId> </dependency> <!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version> 2.6.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version> 2.6.0</version> </dependency> <!-- swagger end -->
3-2 配置swagger spring
@Configuration @EnableSwagger2 //swagger註解 public class SwaggerConfig { @Bean public Docket allInterface() { return new Docket(DocumentationType.SWAGGER_2).groupName("AllInterface(全部接口)")// 定義組 .select() // 選擇那些路徑和api會生成document .apis(RequestHandlerSelectors.basePackage("com.lishun.controller")) // 攔截的包路徑 .paths(regex("/.*"))// 攔截的接口路徑 .build() // 建立 .apiInfo(apiInfo())// 配置說明 .tags(new Tag("index", "起始頁"), getTags()); } /** * @Description:這裏能夠指定其餘tag(對應controller的@Api註解的tags屬性值) * @author lishun * @date 2018/2/28 * @param [] * @return springfox.documentation.service.Tag[] */ private Tag[] getTags() { Tag[] tags = { new Tag("login", "登陸相關") }; return tags; } private ApiInfo apiInfo() { return new ApiInfoBuilder()// .title("swagger api 文檔")// 標題 .description("swagger api 文檔")// 描述 .termsOfServiceUrl("")// .contact(new Contact("", "", ""))// 聯繫 .version("1.0")// 版本 .build(); } }
3-3 統一全部接口返回值(便於前端人員開發,和統一處理controller異常)數據庫
public class ResultBean<T> implements Serializable { /*提示信息*/ public String message = ""; /*狀態碼*/ public Integer code; /*總頁數*/ private long totalPage; /*頁容量*/ private int pages; /*頁碼*/ private int pageNum; /*返回實體信息*/ private T resultData; /*返回集合實體信息*/ private List<T> resultDataList; public ResultBean() { } public ResultBean(List<T> resultData, long totalPage, int pages, int pageNum) { this.resultDataList = resultData; this.totalPage = totalPage; this.pages = pages; this.pageNum = pageNum; } public ResultBean(T resultData) { this.resultData = resultData; } public void setMessage(String message) { this.message = message; } public long getTotalPage() { return totalPage; } public void setTotalPage(long totalPage) { this.totalPage = totalPage; } public int getPages() { return pages; } public void setPages(int pages) { this.pages = pages; } public int getPageNum() { return pageNum; } public void setPageNum(int pageNum) { this.pageNum = pageNum; } public List<T> getResultDataList() { return resultDataList; } public void setResultDataList(List<T> resultDataList) { this.resultDataList = resultDataList; } public void setMessage(String message, Object... args) { this.message = String.format(message, args); } public String getMessage() { return message; } public void setResultData(T resultData) { this.resultData = resultData; } public T getResultData() { return this.resultData; } public Integer getCode() { return code; } public void setCode(Integer code) { this.code = code; } public <T> void setResultBean(Integer code, String message, Object... mesaageFormatArgs) { setCode(code); setMessage(message, mesaageFormatArgs); } }
3-4 統一處理controller異常 api
/** * @author lishun * @Description: 控制器aop攔截 * @date 2017/10/27 */ @Component @Aspect public class ControllerAspect { @Pointcut("execution(public com.lishun.result.ResultBean com.lishun.controller.*.*(..))") public void dataSource(){}; @Around("dataSource()") public Object doAround(ProceedingJoinPoint proceedingJoinPoint) throws Throwable { ResultBean result = null; try { result = (ResultBean<?>)proceedingJoinPoint.proceed(); } catch (Exception e) { result = new ResultBean(); result.setCode(ResultCode.FAILED); result.setMessage(e.getMessage()); e.printStackTrace(); } return result; } }
3-4 contrlloerapp
@RestController @Api(tags = { "index" }) public class IndexController { @GetMapping("/index/{id}") @ApiOperation(value = "findByOne", notes = "獲取一條數據") public ResultBean<String> findByOne(@PathVariable(value = "id") String id) { ResultBean<String> resultBean = new ResultBean<>(); resultBean.setCode(ResultCode.OK); resultBean.setResultData("請求成功"); return resultBean; } @PostMapping("/index/add") @ApiOperation(value = "add", notes = "新增") public ResultBean<String> add(Users users) { ResultBean<String> resultBean = new ResultBean<>(); resultBean.setCode(ResultCode.OK); resultBean.setResultData("請求成功"); return resultBean; } @DeleteMapping("/index/delete/{id}") @ApiOperation(value = "delete", notes = "刪除") public ResultBean<String> delete(@PathVariable(value = "id") String id) { ResultBean<String> resultBean = new ResultBean<>(); resultBean.setCode(ResultCode.OK); resultBean.setResultData("請求成功"); return resultBean; } }
3-5 測試
主要是測試接口api,因此這裏就沒有數據庫訪問的業務邏輯層
啓動項目,訪問http://localhost:8080/swagger-ui.html#/
展開add接口
3-6 注意!!!!! 生成環境須要把swagger禁用,swagger只是適合在開發和測試環境中使用,源代碼