分享一個集成在項目中的REST APIs文檔框架swagger

1 爲何是使用swagger？

　　1-1 當後臺開發人員開發好接口，是否是還要從新書寫一份接口文檔提給前端人員，固然對於程序員最不喜歡的就是書寫文檔(固然文檔是必須的，有利於項目的維護)

　　1-2 當後臺人員開發接口，固然後臺開發者也是須要測試好接口是否可用，當參數少的時候測試還不是很麻煩，當參數有十多個的時候，就須要後臺開發者一個一個的拼接參數，非常耗時間並且還容易寫錯參數名，swagger就很好解決了這個問題(固然也是能夠藉助其餘插件:rest-client工具,PostMan)

2 搭建環境：window,spring boot,swaager,maven

3 開始搭建：搭建過程很簡單，有關於swagger註解本文不詳細敘述，其實只使用經常使用的幾個註解就ok了(@ApiOperation,@EnableSwagger2,@Api)

　　3-1 導入必須jar包 ，修改pom.xml　　

<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　

@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異常　　　　

/**
 * @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 contrlloer

@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只是適合在開發和測試環境中使用，源代碼