一、What is swagger?

官方介紹：Swagger是一個(gè)規(guī)范且完整的框架，提供描述、生產(chǎn)、消費(fèi)和可視化RESTful Web Service。
專業(yè)角度：Swagger是由龐大工具集合支撐的形式化規(guī)范。這個(gè)集合涵蓋了從終端用戶接口、底層代碼庫(kù)到商業(yè)API管理的方方面面。

二、Why use the swagger?

1. 講個(gè)故事：在2014年時(shí)候，我和另一個(gè)小伙伴加入到一個(gè)實(shí)驗(yàn)室，開(kāi)始了我們漫長(zhǎng)的應(yīng)用開(kāi)發(fā)之路（這也是第一次做項(xiàng)目）。因?yàn)橹挥袃蓚€(gè)人，我做后臺(tái)，他做Android，分工很明確的。在一開(kāi)始，我們并沒(méi)有關(guān)注API相關(guān)的內(nèi)容，隨手拈來(lái)，我說(shuō)什么，他就調(diào)用什么。當(dāng)然，也沒(méi)有什么API文檔提供。以至于到現(xiàn)在，我想更新升級(jí)系統(tǒng)，才發(fā)現(xiàn)，我們寫(xiě)的代碼是有多爛，連自己都不忍心去看的。所以說(shuō)在項(xiàng)目開(kāi)始就定一個(gè)契約，雙方（前端后臺(tái)）就API相關(guān)的內(nèi)容，包括路徑、參數(shù)、類型等達(dá)成一致，當(dāng)然，這份契約并不是一旦創(chuàng)建就不能修改的，而且，如果一開(kāi)始沒(méi)有設(shè)計(jì)好，很有可能會(huì)頻繁的修改。
2. 作為一個(gè)很懶的碼代碼的猿呢，對(duì)于一些API的理解總是很模糊不清，但是，總想著能直接驗(yàn)證一下自己的理解就好了，而不是需要去項(xiàng)目寫(xiě)測(cè)試代碼來(lái)驗(yàn)證自己的想法。所以說(shuō)，API文檔應(yīng)該有直接運(yùn)行的能力。而Swagger就是這樣的一個(gè)東西，它可以為已有項(xiàng)目的生成具備執(zhí)行能力的樣式化API文檔，這樣可以極大的方便程序員對(duì)前端后臺(tái)進(jìn)行對(duì)接整合。

三、use the swagger

1. 開(kāi)發(fā)環(huán)境介紹

• maven 3.3
• jdk 8+
• spring 4.2.5
• mybatis 3.4.1
• swagger 1.0.2

2. 在pom.xml文件中添加swagger相關(guān)依賴

<!-- swagger-mvc -->
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.6.6</version>
        </dependency>
        <!-- swagger-mvc -->

3. 自定義對(duì)swagger的配置

對(duì)于swagger的配置，其實(shí)對(duì)自定義一個(gè)與swagger相關(guān)的Config類，可以通過(guò)Java編碼的實(shí)現(xiàn)配置。代碼如下：

package com.hp.common.swagger;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**
 * 
 * @ClassName: SwaggerConfig.java
 * @Description: Swagger配置類
 *
 * @version: v1.1.0
 * @author: xiangdong
 * @date: Mar 16, 2017
 */
public class SwaggerConfig extends WebMvcConfigurerAdapter {

    private SpringSwaggerConfig springSwaggerConfig;

    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }
    
    /**
     * 鏈?zhǔn)骄幊?來(lái)定制API樣式 后續(xù)會(huì)加上分組信息
     * 
     * @return
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){
           return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                    .apiInfo(apiInfo())
                    .includePatterns(".*?");
    }
    
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo("API接口測(cè)試平臺(tái)",
                "提供后臺(tái)所有Restful接口", "www.flyeast.top",
                "shexd1001@gmail.com", "β客棧", "www.flyeast.top");
        return apiInfo;
    }

    @Override
    public void configureDefaultServletHandling(
            DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }
}

3. 注入SwaggerConfig類

上面這段對(duì)swagger進(jìn)行了基本的配置，現(xiàn)在需要將其注入到spring容器中，完成在程序加載之后對(duì)所有接口掃描解析的功能呢，在spring相關(guān)的配置文件中加入以下代碼：

    <!-- swagger配置信息 -->
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

4. 配置需要解析的接口方法

以下代碼是Controller中的一個(gè)方法，@ApiOperation注解對(duì)這個(gè)方法進(jìn)行了說(shuō)明，@ApiParam注解對(duì)方法參數(shù)進(jìn)行了說(shuō)明。關(guān)于其他注解，可以查看源碼或其他幫助文檔；

/**
     * DELETE 刪除用戶
     * @return
     */
    @ApiOperation(value = "刪除用戶信息", notes = "刪除用戶", httpMethod = "DELETE", produces = MediaType.APPLICATION_JSON_VALUE)
    @RequiresPermissions("sysuser:list:delete")
    @RequestMapping(value = "/list/{accountId}/delete", method = RequestMethod.DELETE)
    @ResponseBody
    public AjaxResult delete(@PathVariable Long accountId) {
        systemUserService.deleteSysUser(accountId);
        return success(true);
    }

5. 對(duì)Swagger-UI進(jìn)行配置

Swagger掃描解析得到的是一個(gè)json文檔，所以對(duì)于用戶使用不是很方便，但是通過(guò)swagger-ui，可以友好的展示解析得到的接口說(shuō)明內(nèi)容。
從這里 獲取其所有的 dist 目錄下東西放到需要集成的項(xiàng)目里，本文放入 src/main/webapp/目錄下。
修改index.html文件，默認(rèn)是從連接http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，我們需要將url值修改為http://{ip}:{port}/{projectName}/api-docs的形式，如http://localhost:8080/CloudTi/api-docs

6. 運(yùn)行項(xiàng)目，訪問(wèn)URL

URL是自己在index.html中定義的URL

1489649368(1).jpg

7. 結(jié)束