SpringBoot2-第二章：完善線上APIDocs

pc859107393發表於2019-02-20
Spring BootAPI

上一章我們基本完成了專案框架的搭建，我們目前專案是為了完成一個類似傳統網站的單機伺服器應用，那麼我們接著該做一些什麼呢？

本專案的GitHub：https://github.com/pc859107393/Go2SpringBoot.git

有興趣交流springboot進行快速開發的同學可以加一下下面的企鵝群。

行走的java全棧

實現線上APIDocs

線上ApiDocs是用來做咩的？APIDocs就是對API介面的文件描述形式。可以方便我們線上快速除錯介面。注意：swagger並不能幫助我們實現RESTFul介面，只是說能把RESTFul形式的介面資訊用頁面展示出來。

配置swagger相關設定

首先來講，我們開啟swagger相關的jar包檢視一下swagger內部都存在什麼些東西，swagger本質是一個線上APIDocs，也就是說我們要先從配置著手，但是我們很早以前分析過springfox相關的配置，在這裡我們只需要關注swagger的資源配置就好了，如圖2.1所示。

圖2.1

圖2.1 swagger的靜態資源

在我們以前的專案配置中，所有的資源都是需要合理的分配才能提供給外部訪問，在這裡我們也是需要做同樣的事情才行。

開啟springboot的啟動類檔案，我這裡採用的是kotlin編寫的啟動檔案BaseApplication.kt我們具體的操作如下：

@SpringBootApplication
@EnableWebMvc
@EnableSwagger2
@MapperScan(value = ["cn.acheng1314.base.dao"])
@Configuration
class BaseApplication : WebMvcConfigurer {
    
    //在這裡新增需要被公開的靜態資源
    override fun addResourceHandlers(registry: ResourceHandlerRegistry) {
        //swagger和swagger的第三方皮膚需要被註冊
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/")
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/")
        
        //這裡是註冊的druid的資源
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/")
        
        //這裡是註冊本程式的靜態資源訪問目錄
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/")
    }
    
    //在這裡配置swagger的API分組
    @Bean(name = ["defaultApi"])
    fun createRestApi(): Docket {
        return Docket(DocumentationType.SWAGGER_2)  //Docket，Springfox的私有API設定初始化為Swagger2
                .select()
                //這裡指定專案中需要被掃描的Controller的包路徑
                .apis(RequestHandlerSelectors.basePackage("cn.acheng1314.base.web"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(ApiInfoBuilder()   //設定API文件的主體說明
                        .title("acheng的SpringBoot探索之路ApiDocs")
                        .description("acheng的SpringBoot探索之路")
                        .version("v1.01")
                        .termsOfServiceUrl("https://acheng1314.cn/")
                        .build())
                .groupName("預設介面")
    }
    
    //此處省略其他程式碼······，詳情請上我的github專案檢視
}
複製程式碼

驗證swagger是否生效

接下來我們寫一小段程式碼來試一試，具體程式碼如下：

@Controller
class MainController {

    @GetMapping(value = ["/"], produces = [MediaType.APPLICATION_JSON_UTF8_VALUE])
    @ResponseBody
    @ApiOperation(value = "User輸出測試", notes = "使用者查詢", response = User::class)
    fun MainLocal(): Any = User("程", "18976962315", "123456", "吹牛", Date())

    @GetMapping(value = ["/test"], produces = [MediaType.TEXT_HTML_VALUE])
    fun getTest(map: ModelMap): String {
        map["test"] = MainLocal()
        return "test1"
    }

    @PostMapping(value = ["/json"], produces = [MediaType.APPLICATION_JSON_UTF8_VALUE])
    @ResponseBody
    @ApiOperation(value = "返回提交的User", notes = "返回提交的User", response = User::class)
    fun getJson(@RequestBody user: User): Any {
        println(String.format("使用者資訊：%s", user.toString()))
        return GsonUtil.toJson(user)
    }

    //上面的程式碼中GetMapping和PostMapping 都是SpringMvc中的請求路徑註解。produces指定了返回的內容型別。

}
複製程式碼

執行專案後，結果如圖2.2所示。

圖2.2

圖2.2 部署完成後的swagger截圖

關於上面的@ApiOperation這些註解，包含api關鍵字的都是io.swagger.annotations下面的註解，具體的使用方法可以百度，也可以去springfox的github看demo，當然我在以前的專案中也介紹過。

相關文章