SpringBoot 2.X Kotlin與Swagger2生成API文檔

這裏有個地方須要注意，在測試WebFlux集成Swagger2的時候存在問題，看了官方文檔如今2.9.2尚未集成，因此引入的jar是 spring-boot-starter-web,而不是 spring-boot-starter-webflux

本章目的

在項目中集成文檔及接口測試平臺，使用Swagger2能夠快速幫助咱們編寫最新的API接口文檔，不再用擔憂開會前仍忙於整理各類資料了，間接提高了團隊開發的溝通效率。

添加Swagger2依賴

在pom.xml中加入Swagger2的依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

建立Swagger2配置

package io.intodream.kotlin04.config

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
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.swagger2.annotations.EnableSwagger2

/**
 * @description
 * 構建一個Swagger2配置文件
 * @author Jwenk
 * @copyright intoDream.io 築夢科技
 * @email xmsjgzs@163.com
 * @date 2019-03-31,21:55
 */
@Configuration
@EnableSwagger2
class Swagger2Config {

    @Bean
    fun createRestApi(): Docket {
        return Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
    }

    private fun apiInfo(): ApiInfo {
        return ApiInfoBuilder()
                .title("Spring Boot2.X Kotlin 中使用Swagger2構建RESTFul APIs")
                .description("更多SpringBoot2.X Kotlin 文章請關注:惜魚博客")
                .termsOfServiceUrl("https://www.intodream.io")
                .contact(Contact("惜魚", "https://www.tisnz.com", "xmsjgzs@163.com"))
                .version("1.0.0")
                .build()
    }
}

如上代碼所示，經過@Configuration註解，讓Spring來加載該類配置。再經過@EnableSwagger2註解來啓用Swagger2。

再經過createRestApi函數建立Docket的Bean以後，apiInfo()用來建立該Api的基本信息（這些基本信息會展示在文檔頁面中）。select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展示，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下全部Controller定義的API，併產生文檔內容（除了被@ApiIgnore指定的請求）。

編寫文檔內容

在完成上面的配置後，其實Swagger會自動幫咱們生成API的文檔，可是自動生成的文檔顯示並不友好，咱們一般須要添加一些額外的信息，這時候就須要經過@ApiOperation註解在API上增長說明，經過@ApiImplicitParams、@ApiImplicitParam註解來給參數增長說明。

package io.intodream.kotlin04.web

import io.intodream.kotlin04.model.Student
import io.swagger.annotations.Api
import io.swagger.annotations.ApiImplicitParam
import io.swagger.annotations.ApiOperation
import org.slf4j.Logger
import org.slf4j.LoggerFactory
import org.springframework.web.bind.annotation.*
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.ConcurrentMap

/**
 * @description
 *
 * @author Jwenk
 * @copyright intoDream.io 築夢科技
 * @email xmsjgzs@163.com
 * @date 2019-03-31,22:07
 */
@Api(value = "學生信息相關接口", tags = ["學生"])
@RestController
@RequestMapping("/api/student")
class StudentController {

    private var repository : ConcurrentMap<String, Student> = ConcurrentHashMap<String, Student>()
    private val logger : Logger = LoggerFactory.getLogger(this.javaClass)

    @ApiOperation(value = "保存一條學生信息")
    @ApiImplicitParam(name = "student", value = "學生詳細實體student", required = true, dataType = "Student")
    @PostMapping("/")
    fun save(@RequestBody student: Student): Student? {
        logger.info("請求參數:{}", student)
        return repository.put(student.id, student)
    }

    @ApiOperation(value = "獲取學生列表")
    @GetMapping("/list")
    fun listStudent():List<Student> {
        val studentList = ArrayList<Student>(repository.values)
        logger.info("返回數據:{}", studentList)
        return studentList
    }

    @ApiOperation(value = "經過學生編號獲取學生詳細信息")
    @ApiImplicitParam(name = "studentId", value = "學生編號", required = true, dataType = "String")
    @GetMapping("/info")
    fun studentInfo(@RequestParam studentId: String): Student? {
        val student : Student? = repository.get(studentId)
        logger.info("studentId:{}, 對應的數據:{}", student)
        return student
    }

    @ApiImplicitParam(name = "studentId", value = "學生編號", required = true, dataType = "String")
    @ApiOperation(value = "刪除學生信息")
    @DeleteMapping("/")
    fun deleteStudent(@RequestParam studentId: String): String {
        logger.info("刪除學生編號:{}", studentId)
        repository.remove(studentId)
        return "success"
    }
}

完成上述代碼添加上，啓動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html。就能看到前文所展現的RESTful API的頁面。咱們能夠再點開具體的API請求，以POST類型的/api/student/請求爲例，可找到上述代碼中咱們配置的Notes信息以及參數student的描述信息，以下圖所示。

API文檔訪問與調試

在上圖請求的頁面中，咱們看到student的Example Value是個輸入框？是的，Swagger除了查看接口功能外，還提供了調試測試功能，咱們能夠點擊上圖中右側的Model Schema（黃色區域：它指明瞭User的數據結構），此時Example Value中就有了student對象的模板，咱們只須要稍適修改，點擊下方「Try it out！」按鈕，便可完成了一次請求調用！

到此咱們集成Swagger2就完成了，你們能夠多測試一下看返回結果是否正確，感受是否是寫接口文檔方便了不少呢。