ApiBoot 文档

ApiBoot 整合 Swagger2

ApiBoot通过整合Swagger2完成自动化接口文档生成,只需要一个简单的注解我们就可以实现文档的开启,而且文档上面的所有元素都可以自定义配置,通过下面的介绍来详细了解ApiBoot Swagger的简易之处。

引入ApiBoot Swagger

pom.xml配置文件内通过添加如下依赖进行集成:

<!--ApiBoot Swagger-->
<dependency>
	<groupId>org.minbox.framework</groupId>
	<artifactId>api-boot-starter-swagger</artifactId>
</dependency>

注意:如果未添加ApiBoot版本依赖,请访问版本依赖查看添加方式。

@EnableApiBootSwagger

在添加依赖后需要通过@EnableApiBootSwagger注解进行开启ApiBoot Swagger相关的配置信息自动化构建,可以配置在XxxApplication入口类上,也可以是配置类,让SpringBoot加载到即可。

相关配置

配置参数 参数介绍 默认值
api.boot.swagger.enable 是否启用 true
api.boot.swagger.title 文档标题 ApiBoot快速集成Swagger文档
api.boot.swagger.description 文档描述 ApiBoot通过自动化配置快速集成Swagger2文档,仅需一个注解、一个依赖即可。
api.boot.swagger.base-package 文档扫描的package XxxApplication同级以及子级package
api.boot.swagger.version 文档版本号 api.boot.version
api.boot.swagger.license 文档版权 ApiBoot
api.boot.swagger.license-url 文档版权地址 https://github.com/hengboy/api-boot
api.boot.swagger.contact.name 文档编写人名称 恒宇少年
api.boot.swagger.contact.website 文档编写人主页 https://blog.yuqiyu.com
api.boot.swagger.contact.email 文档编写人邮箱地址 jnyuqy@gmail.com
api.boot.swagger.authorization.name 整合Oauth2后授权名称 ApiBoot Security Oauth 认证头信息
api.boot.swagger.authorization.key-name 整合Oauth2后授权Header内的key-name Authorization
api.boot.swagger.authorization.auth-regex 整合Oauth2后授权表达式 ^.*$

以上是目前版本的所有配置参数,大多数都存在默认值,可自行修改。

整合ApiBoot Security Oauth

如果你的项目添加了Oauth2资源保护,在Swagger界面上访问接口时需要设置AccessTokenHeader才可以完成接口的访问,ApiBoot Security Oauth默认开放Swagger所有相关路径,如果项目内并非通过ApiBoot Security Oauth2来做安全认证以及资源保护,需要自行开放Swagger相关路径。

整合ApiBoot Security Oauth很简单,访问ApiBoot Security Oauth 查看。

携带Token访问Api

启动添加ApiBoot-Swagger依赖的项目后,访问http://localhost:8080/swagger-ui.html页面查看Swagger所生成的全部文档,页面右侧可以看到Authorize,点击后打开配置AccessToken的界面,配置的AccessToken必须携带类型,如:Bearer 0798e1c7-64f4-4a2f-aad1-8c616c5aa85b

注意:通过ApiBoot Security Oauth所获取的AccessToken类型都为Bearer

ApiBoot Swagger + @EnableWebMvc = 404?

@EnableWebMvc注解使用后会覆盖掉SpringBoot默认的资源映射路径/static, /public, META-INF/resources, /resources等存放静态资源的目录。

Swagger资源都存在在META-INF/resources目录下,所以会出现404的情况,只需要添加自定义的资源映射处理就可以再次访问默认资源路径下的文件,如下所示:

@Configuration
@EnableWebMvc
public class ApiBootResourceConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("/");
    }
}