swagger-ui 系統配置過程（基於spring+springmvc+swagger+springfox配置 web-api 管理系統）

web工程部分框架信息：spring springmvc swagger springfox maven

參考文檔：
https://www.cnblogs.com/exmyth/p/7183753.html
https://www.cnblogs.com/arctictern/p/7498838.html
https://my.oschina.net/wangmengjun/blog/907679
http://springfox.github.io/springfox/docs/current/

---

pom.xml 對於 swagger-ui 的依賴

<!-- https://mvnrepository.com/artifact/com.mangofactory/swagger-springmvc -->
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.9.5</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-petstore -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-petstore</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-data-rest</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>23.4-jre</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-javadoc-plugin -->
        <dependency>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
        </dependency>

工程結構（僅做爲參考）

配置步驟以下：

一、建立 swagger 的配置類（若是要自定義一些內容，請參考官網 API 的描述）

@Configuration      // 這是控制開關
@EnableSwagger2     // 這是用了 swagger2
@EnableWebMvc   // 這是由於工程用的 springmvc 
@ComponentScan(basePackages = {"controller"})     //這裏也許能夠不用，暫沒去求證
public class SwaggerConfig {
    /**
     * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple swagger groups i.e. same code base multiple swagger resource listings.
     */
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()            //select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展示
                .apis(RequestHandlerSelectors.any()) //掃描指定包內全部Controller定義的Api，併產生文檔內容（除了被@ApiIgnore指定的請求）。
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo()); //用來建立該Api的基本信息（這些基本信息會展示在文檔頁面中）
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Spring-mvc中使用Springfox集成Swagger2構建APIs").build();
    }

}

二、在 spring-mvc.xml 中添加掃描文件的信息

<!-- Enables swgger ui -->
    <bean class="swagger.swaggerConfig.SwaggerConfig" />

    <!-- 這裏實際上是爲了解決靜態資源訪問的問題, 這是一種解決方式 -->
    <mvc:default-servlet-handler/>

三、在 spring-mvc的攔截器作處理，即在 web.xml 中追加

<!-- springMVC核心配置 -->
    <servlet>
        <servlet-name>dispatcherServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <!--spingMVC的配置路徑 -->
            <param-value>classpath:springmvc/spring-mvc.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <!-- 攔截設置 -->
    <servlet-mapping>
        <servlet-name>dispatcherServlet</servlet-name>
        <url-pattern>*.do</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/swagger-ui.html</url-pattern>
    </servlet-mapping>

    <!--<servlet-mapping>-->
        <!--<servlet-name>default</servlet-name>-->
        <!--<url-pattern>*.png</url-pattern>-->
    <!--</servlet-mapping>-->

    <!--<servlet-mapping>-->
        <!--<servlet-name>default</servlet-name>-->
        <!--<url-pattern>*.js</url-pattern>-->
    <!--</servlet-mapping>-->

    <!--<servlet-mapping>-->
        <!--<servlet-name>default</servlet-name>-->
        <!--<url-pattern>*.css</url-pattern>-->
    <!--</servlet-mapping>-->

    <servlet-mapping>
        <servlet-name>dispatcherServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>dispatcherServlet</servlet-name>
        <url-pattern>/v2/api-docs</url-pattern>
    </servlet-mapping>

四、從https://github.com/swagger-api/swagger-ui 獲取其全部的 dist 目錄下東西放到須要集成的項目裏

五、並打開復制過來的 index.html，修改 url

六、再在 spring-mvc.xml 中追加資源映射

<mvc:resources mapping="*.html" location="apidoc/resources"/>
    <mvc:resources mapping="/**" location="apidoc/"/>

    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/>
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />

此時 spring-mvc.xml 看起來可能就像這樣：


注意下述內容最好保持一致（由於我也沒花時間去求解，以前由於一些處理，訪問時遇到了"base URL......"吧啦吧啦的模態框）



七、啓動運行成功後，訪問地址 http://localhost:8080/swagger-ui.html
看起來像這樣子：

---

我的目前對於 swagger 的用途（優缺點）理解

優勢

• 一、不用在 coding 以後再去寫接口文檔，能夠實時同步更新
• 二、不須要重複造輪子，寫解析器（固然定製化的會輕便靈活得多）
• 三、能夠用於後臺的 web 接口的快速調試
• 四、有配套的工具來支撐擴展（見 swagger 的官網 tools 欄目）

缺點

• 一、有學習成本（如環境配置、註解使用等）
• 二、可能會和真實開發的工程存在組件的衝突
• 三、（最明顯的）工做量可能會增長，這個須要開發崗的慎重評估。好比非標準的 restful api設計；工程的複雜度設計如 DTO 徹底就是對應 BO 時，須要拆成標準的設計；API 編寫的工做量受框架約束等等
• 四、文檔界面雖美觀，可是閱讀性不必定直觀
• 五、沒有自研的工具給力，對於測試工程師來講須要考慮使用 swagger 後解決方案
• 六、工程之間是隔離的