SpringBoot2-第二章：完善在线APIDocs

上一章我们基本完成了项目框架的搭建，我们目前项目是为了完成一个类似传统网站的单机服务器应用，那么我们接着该做一些什么呢？

本项目的GitHub：https://github.com/pc859107393/Go2SpringBoot.git

有兴趣交流springboot进行快速开发的同学可以加一下下面的企鹅群。

实现在线APIDocs

在线ApiDocs是用来做咩的？APIDocs就是对API接口的文档描述形式。可以方便我们在线快速调试接口。注意：swagger并不能帮助我们实现RESTFul接口，只是说能把RESTFul形式的接口信息用页面展示出来。

配置swagger相关设置

首先来讲，我们打开swagger相关的jar包查看一下swagger内部都存在什么些东西，swagger本质是一个在线APIDocs，也就是说我们要先从配置着手，但是我们很早以前分析过springfox相关的配置，在这里我们只需要关注swagger的资源配置就好了，如图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 部署完成后的swagger截图

关于上面的@ApiOperation这些注解，包含api关键字的都是io.swagger.annotations下面的注解，具体的使用方法可以百度，也可以去springfox的github看demo，当然我在以前的项目中也介绍过。