β

SpringBoot2-第二章:完善在线APIDocs

Harries Blog™ 22 阅读

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

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

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

SpringBoot2-第二章:完善在线APIDocs

实现在线 API Docs

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

配置 swagger相关设置

首先来讲,我们打开swagger相关的jar包查看一下swagger内部都存在什么些东西,swagger 本质 是一个在线APIDocs,也就是说我们要先从配置着手,但是我们很早以前分析过 spring fox相关的配置,在这里我们只需要关注 swagger的资源配置 就好了,如图2.1所示。

SpringBoot2-第二章:完善在线APIDocs

图2.1 swagger的静态资源

在我们以前的项目配置中,所有的资源都是需要合理的分配才能提供给外部访问,在这里我们也是需要做同样的事情才行。

打开springboot的启动类文件,我这里采用的是kotlin编写的启动文件 Base App li cat ion.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所示。

SpringBoot2-第二章:完善在线APIDocs

图2.2 部署完成后的swagger截图

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

原文

https://juejin.im/post/5b0e46adf265da0923154bc5

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。 PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处: Harries Blog™ » SpringBoot2-第二章:完善在线APIDocs

作者:Harries Blog™
追心中的海,逐世界的梦
原文地址:SpringBoot2-第二章:完善在线APIDocs, 感谢原作者分享。

发表评论