SpringBoot2-第二章：完善在線APIDocs

時間 2019-11-16

標籤 springboot2 springboot 第二完善在線 apidocs 欄目 Spring 简体版

原文原文鏈接

上一章咱們基本完成了項目框架的搭建，咱們目前項目是爲了完成一個相似傳統網站的單機服務器應用，那麼咱們接着該作一些什麼呢？html

本項目的GitHub：https://github.com/pc859107393/Go2SpringBoot.gitjava

有興趣交流springboot進行快速開發的同窗能夠加一下下面的企鵝羣。git

實如今線APIDocs

在線ApiDocs是用來作咩的？APIDocs就是對API接口的文檔描述形式。能夠方便咱們在線快速調試接口。注意：swagger並不能幫助咱們實現RESTFul接口，只是說能把RESTFul形式的接口信息用頁面展現出來。github

配置swagger相關設置

首先來說，咱們打開swagger相關的jar包查看一下swagger內部都存在什麼些東西，swagger本質是一個在線APIDocs，也就是說咱們要先從配置着手，可是咱們很早之前分析過springfox相關的配置，在這裏咱們只須要關注swagger的資源配置就行了，如圖2.1所示。web

圖2.1 swagger的靜態資源spring

在咱們之前的項目配置中，全部的資源都是須要合理的分配才能提供給外部訪問，在這裏咱們也是須要作一樣的事情才行。json

打開springboot的啓動類文件，我這裏採用的是kotlin編寫的啓動文件BaseApplication.kt咱們具體的操做以下：api

@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是否生效

接下來咱們寫一小段代碼來試一試，具體代碼以下：springboot

@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指定了返回的內容類型。

}
複製代碼