發現一位博主寫的特別棒 強烈推薦參考他的：大牛的網址

由於Spring Boot能夠快速開發、便捷部署等特性，相信有很大一部分Spring Boot的使用者會用來構建RESTful API。而我們構建RESTful API的目的通常都是由於多終端的原因，這些終端會共用很多底層業務邏輯，因此我們會抽象出這樣一層來同時服務於多個移動端或者Web前端。

這樣一來，我們的RESTful API就有可能要面對多個開發人員或多個開發團隊：IOS開發、Android開發或是Web開發等。為了減少與其他團隊平時開發期間的頻繁溝通成本，傳統做法我們會建立一份RESTful API文件來記錄所有介面細節，然而這樣的做法有以下幾個問題：
由於介面眾多，並且細節複雜（需要考慮不同的HTTP請求型別、HTTP頭部資訊、HTTP請求內容等），高質量地建立這份文件本身就是件非常吃力的事，下游的抱怨聲不絕於耳。
隨著時間推移，不斷修改介面實現的時候都必須同步修改介面文件，而文件與程式碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象。

為了解決上面這樣的問題，本文將介紹RESTful API的重磅好夥伴Swagger2，它可以輕鬆的整合到Spring Boot中，並與Spring MVC程式配合組織出強大RESTful API文件。它既可以減少我們建立文件的工作量，同時說明內容又整合入實現程式碼中，讓維護文件和修改程式碼整合為一體，可以讓我們在修改程式碼邏輯的同時方便的修改文件說明。另外Swagger2也提供了強大的頁面測試功能來除錯每個RESTful API。

springfox是通過註解的形式自動生成API文件的，利用它，可以很方便的學些restful API；swagger主要使用者展示springfox生成的API文件，而且還提供測試介面，自動顯示json格式的響應，大大方便了後臺開發人員和前端的溝通與聯調成本。

swagger

swagger是一個規範的完整的框架，使用者生成、描述、呼叫和視覺化RESTful風格的Web服務。總體的目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密繼承到伺服器端的diamante，允許API來始終保持同步。Swagger讓部署管理和使用功能強大的API從未如此簡單

springfox-swagger

swagger的功能非常強大，spring這個大神就開始試圖想把swagger繼承到自己的專案中，就有了後來的spring-swagger，再後來又演變成了springfox。雖然是通過plug的方式把swagger整合進來，但是它本身對api的生成，主要還是依靠swagger實現的。

SpringFox的大致原理

springfox的大致原理就是，在專案啟動的過程中，spring上下文的初始化的過程，框架自動根據配置家在一些swagger相關的bean到當前的上下文，並且自動掃描系統中可能需要生成的api文件的那些類，並生成響應的資訊快取起來。一般的都會掃描控制層Controller類，根據這些Controller類中的功能方法自動生成API介面文件。

使用步驟：（使用的軟體：IDEA，語言：kotlin）

1.在pom.xml中新增maven依賴

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <version>1.1.2.RELEASE</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
        </dependency>

2.新增Swagger2的配置檔案：configuration

需要特別注意的是swagger scan base package，這是掃描註解的配置，即你的介面位置。

    import org.springframework.context.annotation.Bean
    import org.springframework.context.annotation.Configuration
    import org.springframework.http.ResponseEntity
    import springfox.documentation.builders.ApiInfoBuilder
    import springfox.documentation.builders.PathSelectors
    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.swagger.web.UiConfiguration
    import springfox.documentation.swagger2.annotations.EnableSwagger2

    @Configuration
    @EnableSwagger2
    class Swagger2Config {

    @Bean
    fun restfulApi(): Docket {
        return Docket(DocumentationType.SWAGGER_2)
                .genericModelSubstitutes(ResponseEntity::class.java)
                .useDefaultResponseMessages(true)
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.company.service.web"))
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .apiInfo(apiInfo())
    }

    private fun apiInfo(): ApiInfo {
        return ApiInfoBuilder()
                .title("API文件")
                .description(this.description)
                .termsOfServiceUrl("http://路徑.com")
                .contact(Contact("name", "http://name.com", "[email protected]"))
                .version("1.0.0")
                .build()
    }

    private val description = "Api 文件規範."
}

這裡的@Configuration註解，讓spring載入配置，@EnableSwagger2啟用Swagger2
再通過createRestApi函式建立Docket的Bean之後，apiInfo()用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）。select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，併產生文件內容（除了被@ApiIgnore指定的請求）。

3.在API上做一些宣告：在Controller類中新增相關的swagger註解。但是有一個要求，這個Controller類一定要讓上一步配置類的@ComponentScan掃描到；

@RestController
@Api(value = "User", description = "the chapter of user")
@RequestMapping("/users", produces = arrayOf(MediaType.APPLICATION_JSON_UTF8_VALUE))
class UserController {

    @Resource private lateinit var userService: IUserService
    @Resource private lateinit var orgResponse: OrgResponse
    @Resource private lateinit var iDGenerator: IDGenerator

    @ApiOperation(value = "createUser", notes = "建立一個使用者")
    @ApiImplicitParam(name = "zy", value = "使用者名稱", paramType = "path", required = true, dataType = "String")
    @PostMapping(consumes = arrayOf(MediaType.APPLICATION_JSON_UTF8_VALUE))
    fun create(@Valid @RequestBody user: SysUser,@PathVariable userName:String): ResponseEntity<Any> {
       return null
    }
}

使用Spring Rest Docs 可以通過測試生成響應的Asciidoc片段，mockmvc類是屬於dosc的。

@RunWith(SpringJUnit4ClassRunner::class)
@SpringBootTest
class UserControllerTest {

    @Resource private lateinit var context: WebApplicationContext
    private lateinit var mockMvc: MockMvc

    @Rule @JvmField var restDocumentation = JUnitRestDocumentation("target/asciidoc/snippets")

    @Before
    fun setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(context)
                .apply<DefaultMockMvcBuilder>(documentationConfiguration(this.restDocumentation))
                .build()
    }

    @After
    fun tearDown() {
    }

    @Test
    fun create() {
        val json = """
                {
                    "userName": "zy",
                    "email": "[email protected]",
                    "password": "zy2017"
                }
             """
        val request = post("/users")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(json)
                .accept(MediaType.APPLICATION_JSON_UTF8)

        this.mockMvc.perform(request)
                .andExpect(status().isCreated)
                .andDo(print())
                //spring Rest Docs生成Asciidoc片段
                .andDo(document("createUser", preprocessResponse(prettyPrint())))

    }

生成html和pdf

1.首先在index中引入整個asciidoc的三行程式碼：

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

2.在pom.xml檔案中新增asciidoctor的外掛

            <!--asciidoc-->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <includes>
                        <include>**/*Documentation.java</include>
                    </includes>
                </configuration>
            </plugin>
            <!-- Run the generated asciidoc through Asciidoctor to generate
                 other documentation types, such as PDFs or HTML5 -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.11</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered/>
                        <hardbreaks/>
                        <sectlinks/>
                        <sectanchors/>
                        <generated>${generated.asciidoc.directory}</generated>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

3.現在執行SwaggerTest，整合片段成html檔案

import io.github.robwin.markup.builder.MarkupLanguage
import io.github.robwin.swagger2markup.GroupBy
import io.github.robwin.swagger2markup.Swagger2MarkupConverter
import org.junit.Before
import org.junit.Test
import org.junit.runner.RunWith
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.http.MediaType
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get
import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status
import org.springframework.test.web.servlet.setup.MockMvcBuilders
import org.springframework.web.context.WebApplicationContext
import springfox.documentation.staticdocs.Swagger2MarkupResultHandler.outputDirectory
import springfox.documentation.staticdocs.SwaggerResultHandler
import javax.annotation.Resource


/**
 * Description
 * @date 2017-04-17
 */
@RunWith(SpringJUnit4ClassRunner::class)
@SpringBootTest
//@AutoConfigureRestDocs(outputDir = "target/asciidoc/snippets")
class Swagger2MarkupTest {

    @Resource private val context: WebApplicationContext? = null
    private lateinit var mockMvc: MockMvc

    @Before
    fun setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context!!).build()
    }

    private val snippetDir = "target/asciidoc/snippets"
    private val outputDir = "target/asciidoc/generated"

    @Test
    @Throws(Exception::class)
    fun convertToAsciiDoc() {

        // 得到swagger.json,寫入outputDir目錄中
        this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
                .andExpect(status().isOk)
                .andReturn()

        // 讀取上一步生成的swagger.json轉成asciiDoc,寫入到outputDir
        // 這個outputDir必須和外掛裡面<generated></generated>標籤配置一致
        Swagger2MarkupConverter.from(outputDir + "/swagger.json")
                .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
                .withExamples(snippetDir) //插入測試生成的片段
                .build()
                .intoFolder(outputDir) // 輸出
    }

    @Test
    @Throws(Exception::class)
    fun convert2AsciiDoc() {
        this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(outputDirectory(outputDir)
                        .withPathsGroupedBy(GroupBy.TAGS)
                        .withExamples(snippetDir)
                        .build())
                .andExpect(status().isOk)
    }

}

執行測試和maven之後得到下面這樣的：

生成的api.xml將是這樣的：

常用的註解：
* @Api：將Controller標記為Swagger文件資源。
* @ApiOperation：描述一個類的一個方法，或者說一個介面
* @ApiImplicitParams ：多個引數描述
* @ApiImplicitParam：單個引數描述
* @ApiModel：用物件來接收引數
* @ApiModelProperty：用物件接收引數時，描述物件的一個欄位
其它
* @ApiResponse：HTTP響應其中1個描述
* @ApiResponses：HTTP響應整體描述

詳細的引數說明：
*@Api（value = “api的name”，notes = “描述”）
*@ApiOperation(value = “操作的名稱”, notes = “對操作的描述”)
*@ ApiResponse(code = 返回的數字碼, message = “對應的訊息內容”, response = 返回值類)
*@ApiImplicitParam(name = “引數名稱”, value = “引數的描述，或者值”, paramType = “引數位置”, required = true（boolean值，是否必須提供）, dataType = “引數的資料型別”)
(((其中，位置引數型別paramType分為以下幾種，是根據它被什麼註解而對應的型別，這裡的型別一定要和方法中的引數註解要相同，要不然獲取不到值。下面是簡介：
@RequestHeader—–paramType = “header”
@RequestParam—–paramType = “query”
@PathVariable—–paramType = “path”
@RequestBody—–paramType = “body”

4.設定訪問API doc的路由

在配置檔案application.yml中宣告：

springfox.docmentation.swagger.v2.path:/api-docs

這個path就是json的訪問request mapping，可以自定義，防止與自身程式碼衝突。
API doc的顯示路由是：http://localhost:8080/swagger-ui.html
啟動SpringBoot程式，訪問上面的網址，就能夠看到前文所展示的restful API的介面了。
我們可以在這裡輸入引數資訊進行測試：

插入圖片