一般都是在已經很完善的專案裡面，去整合這個 swagger ，我這就反其道而行之，仔細看看這個 swagger 到底都依賴些什麼jar包。
讓你好好了解下這個東西，出了些問題的話，也可以簡單的處理下。
我這就是以一個非常簡單的 maven hello world 專案的基礎上，去整合這個 swagger 的實踐記錄。
所以，你這得有個如上的簡單專案。
我這有以前的連結，可以供小白們參考。

先是建立個簡單的hello world 的 maven web專案，參見下面的連結。

然後就是在上面的簡單專案裡面加上spring mvc 相關的東西。參見下面的連結。

上面的2個連結都仔細實踐過之後，準備工作就OK啦

開始，怎麼整合這個 swagger 

先是pom.xml的 dependency 依賴的新增。

為了一覽全貌，我就把全部的依賴放這了，因為是個超簡單的專案，所以這個依賴很少，方便觀眾，看清楚，每個依賴都是幹啥的。

    <dependencies>
        <!-- Spring MVC support -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
            <version>4.1.4.RELEASE</version>
        </dependency>
        <!--JSTL-->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>jstl</artifactId>
            <version>1.2</version>
            <scope>runtime</scope>
        </dependency>
        <!-- swagger2 核心依賴 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- swagger-ui 為專案提供api展示及測試的介面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- 整合 swagger 的時候，缺少這個 jar包是不OK的-->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.2.3</version>
        </dependency>

    </dependencies>
 

我看有的老鐵的文章裡面，信誓旦旦的說，老簡單啦，就需要特別引入 springfox-swagger2 和springfox-swagger-ui  2個jar依賴，就是前面的兩個，沒有我這個地方的第三個。

也許他不是，從一個完全乾淨的專案開始整的，搞不好，他的那個專案裡面已經有了我上面提供的第三個的依賴。

如果，你覺得溼胸我說的有問題，可以實驗一把，把我後面的那個依賴刪除了，測試一下。就會發現，index頁面跑起來沒問題，但是訪問咱自己寫的controller的時候，就炸啦。我這有如下的報錯圖，供各位參考。

可以看到是少了個這，

然後再給各位觀眾看看，當新增上剛剛的三個依賴後，整個專案的各個jar包的依賴關係圖

注意啦，有些老鐵嫌棄溼胸的這個圖上面的字太小啦，唉，這能怪我嗎。。。

你可以，按我下圖操作，在新標籤頁，開啟這個圖，估計可以看到大圖啦。

這下就可以看到整個spring mvc 專案裡面的各個jar包的依賴關係啦。

要是還嫌棄小，老鐵，你down下來，不就可以放大看了嗎？

是不是有耳目一新的感覺，估計以前誰的文章，都沒這麼直觀的告訴你，一個專案的jar包之間的依賴關係是這麼來的吧。

想知道上面的這個依賴關係圖怎麼來的嗎？

需要新增一句

<mvc:default-servlet-handler />

為了明瞭的展示問題，我這就把我的全部貼出來。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <!-- 開啟spring的掃描注入，使用如下註解 -->
    <!-- @Component,@Repository,@Service,@Controller-->
    <context:component-scan base-package="com.lxk"/>

    <!-- 開啟springMVC的註解驅動，使得url可以對映到對應的controller -->
    <mvc:annotation-driven />
    <mvc:default-servlet-handler />
    <!-- 檢視解析 -->
    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix" value="/WEB-INF/views/"/>
        <property name="suffix" value=".jsp"/>
    </bean>

</beans>

有些老鐵說，要是專案配置了攔截器，需要新增如下的一些配置，

            <mvc:exclude-mapping path="/swagger*/**"/>
            <mvc:exclude-mapping path="/v2/**"/>
            <mvc:exclude-mapping path="/webjars/**"/>

我註釋掉，頁面照樣可以OK。

最後，就是Java程式碼的實際操作啦。分2部分，一個是Java不分的配置，一個是實際你需要完善的 那些個資訊。

package com.lxk.utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author lxk on 2017/12/18
 */
@Configuration
@EnableSwagger2
@EnableWebMvc
public class ApiConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("大師兄整合swagger的介面測試")
                .description("聞道有先後，術業有專攻。")
                .termsOfServiceUrl("http://blog.csdn.net/qq_27093465?viewmode=contents")
                .contact(new Contact("csdn大師兄", "http://blog.csdn.net/qq_27093465", "[email protected]"))
                .license("")
                .licenseUrl("")
                .version("1.0.0")
                .build();
    }

}

最最後，就是在controller裡面的請求上使用註解，完善最後的結果圖。

package com.lxk.controller;

import com.lxk.model.Student;
import com.lxk.service.StudentService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.ModelAndView;

import javax.annotation.Resource;

/**
 * Created by lxk on 2017/3/27
 */
@Controller
@RequestMapping("student")
public class StudentController {

    @Resource(name = "studentService")
    private StudentService studentService;

    //@ResponseBody//(之前我因為加了這個註解，導致頁面訪問一直是406錯誤，註釋了就好啦，具體為啥我暫時還不知道)
    @ApiOperation(value = "獲得所有的學生物件list", notes = "get請求，查詢所有的學生。")
    @RequestMapping(value = "/getAllStudent", method = RequestMethod.GET)
    public ModelAndView getAllStudent() {
        ModelAndView mav = new ModelAndView();
        mav.setViewName("studentDisplay");
        mav.addObject("students", studentService.getAllStudent());
        return mav;
    }

    @ApiOperation(value = "根據學生的name，獲得單個學生的資訊", notes = "根據學生的name，查詢學生物件的資訊。")
    @ApiImplicitParam(name = "name", value = "學生的名稱", required = true, dataType = "String")
    @ResponseBody
    @RequestMapping(value = "getStudentByName", method = RequestMethod.POST)
    public String getStudentByName(String name) {
        return "";
    }

    @ApiOperation(value = "根據學生的name和age，獲得單個學生的資訊", notes = "根據學生的name和age，查詢學生物件的資訊。")
    @ApiImplicitParams({@ApiImplicitParam(name = "name", value = "學生名稱", required = true, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "學生年齡", required = true, dataType = "int")})
    @ResponseBody
    @RequestMapping(value = "getStudentByNameAndAge", method = RequestMethod.POST)
    public String getStudentByName(String name, int age) {
        return "";
    }

    @ApiOperation(value = "新建學生物件到資料庫", notes = "新建資料到資料庫。")
    @ApiImplicitParam(name = "student", value = "學生物件", required = true, dataType = "Student")
    @ResponseBody
    @RequestMapping(value = "createNewStudent", method = RequestMethod.POST)
    public String create(@RequestBody Student student) {
        return "";
    }
}

http://localhost:8080/lxk/swagger-ui.html#/

這地方的lxk，是我配置tomcat的時候給配置上去的，各位因地制宜哦。

然後就是執行結果圖。

這就是最終的執行結果。

圖上的箭頭，就是剛剛在Java程式碼裡面2個地方寫的資訊。

還有啊，這幾個請求是可以點開的，裡面還有詳情呢。老鐵們實踐的時候，可以點開看看。我就不截圖啦。

至此，這個整合的實踐，就算完啦。

說下感想：

這個東西，也不是很好呀，只是說，作為開發者，你省卻了去寫開發文件的時間，但是這個頁面出來之後，並不是很好用。而且，你在controller裡面加的那些個註解，以及註解上使用的引數，也就是你寫的那些個描述資訊，這都是和程式碼的邏輯沒什麼關係的，用高階點的術語，就是這個非常的入侵，非常的不友好。我們這也是說領導要讓我們開發寫開發文件，有什麼請求，請求的引數，都返回什麼，都是幹啥的，都是什麼請求方式等等這些資訊。因為這個文件的書寫和維護很麻煩的，所以，打算使用這個 swagger 外掛來簡化這個 工作。但是，我覺得這東西並不好啊。非常不好。我個人是這麼覺得的。

我寫完文章，給自己點個贊，不過分吧，

不過分，那我可就點啦啊。

我先點為敬，你們隨意。大家隨意。不要客氣。。。

想要原始碼嗎？

不免費送啦，你懂的。