Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，
在Springboot项目中要集成swagger需要要做哪些工作？
1. 依赖包引入
在pom文件中引入swagger-spring-boot-starter，knife4j-spring-boot-starter包。
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.1</version>
</dependency>
2. 配置修改
首先实现要一个 SwaggerConfig 的配置类型，该配置文件实现接口WebMvcConfigurer。同时加上注解 @EnableSwagger2，启动swager。
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
}
然后构建 Docket bean 组件，每个 Docket bean 组件构建一个API接口文档分组。Docket 派生自DocumentationPlugin，是一个描述API接口分组信息的类，该类通过 builder 模式构建接口文档实体。
@Bean
public Docket newApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo(" 接口分组1"))
.groupName("接口分组1")
.genericModelSubstitutes(DeferredResult.class)
.forCodeGeneration(false)
.select()// 选择匹配的控制器或URL路径用于生产 API document
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))// 对所有api进行监控
.paths(PathSelectors.regex("api1/.*"))
.build();
}
@Bean
public Docket appApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo(" 接口分组2"))
.groupName("接口分组2")
.genericModelSubstitutes(DeferredResult.class)
.forCodeGeneration(false)
.select()// 选择匹配的控制器或URL路径用于生产 API
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))// 对所有api进行监控
.paths(PathSelectors.regex("api2/.*"))
.build();
}
构建API接口文档实例时需要注意接口的扫描范围，接口扫描范围可以通过 正则表达式、请求注解等多种方式配置。
最后将前端资源所在的路径告知 spring mvc：
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
启用安全策略
安全前端页面资源文件访问和api接口访问安全。前端页面访问资源配置只需要在shiro配置文件添加如下代码即可。
chain.put("/doc.html", "anon");
chain.put("/swagger-ui.html", "anon");
chain.put("/v2/**", "anon");
chain.put("/swagger-resources/**", "anon");
chain.put("/webjars/**", "anon");
API接口安全机制，这里选择了在http头部 accesstoken 的方式实现安全访问（具体实现可以参考Shiro OAuth2实现机制）。
首先在swaggerconfig 配置类中添加两个新方法
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList<>();
apiKeyList.add(new ApiKey("Authorization", AccessTokenLoginServiceImpl.ACCESSTOKEN_HEADER, "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
//设置不需要安全验证的地址
.forPaths(PathSelectors.regex("^(?!auth).*$|/api/jwtToken"))
.build());
return securityContexts;
}
然后修改api接口文档实例，追加两行代码：
.securitySchemes(securitySchemes())
.securityContexts(securityContexts()
修改后为：
@Bean
public Docket newApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo(" 接口分组1"))
.groupName("接口分组1")
.genericModelSubstitutes(DeferredResult.class)
.forCodeGeneration(false)
.select()// 选择哪些路径和API会生成document
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))// 对所有api进行监控
.paths(PathSelectors.regex("api1/.*"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts();
}
@Bean
public Docket appApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo(" 接口分组2"))
.groupName("接口分组2")
.genericModelSubstitutes(DeferredResult.class)
.forCodeGeneration(false)
.select()// 选择哪些路径和API会生成document
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))// 对所有api进行监控
.paths(PathSelectors.regex("api2/.*"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts();
}
给需要接口的类或方法添加注解
修改控制器，添加注解如：
@Api(tags = "接口分组DEMO")
@RestController
@RequestMapping("/api1/demo")
public class Demo1Controller {
@ApiOperation(value = "接口描述信息")
@PostMapping("/post")
public Result getEmployeeInfo(@RequestBody DemoRequest info) {
Result result = new ApiResult();
return result.setData(data);
}
}
swagger常用注解：
- @Api: 表示标识这个类是swagger的资源
- @ApiOperation: 表示一个http请求的操作
- @ApiParam: 表示对参数的添加元数据（说明或是否必填等）
- @ApiModel: 表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty: 表示对model属性的说明或者数据操作更改
- @ApiIgnore: 表示这个方法或者类被忽略
- @ApiImplicitParam: 表示单独的请求参数
- @ApiImplicitParams: 包含多个 @ApiImplicitParam
发布配置
一般swagger接口都是开发时使用。要在发布到生产环境时屏蔽swagger访问有两种方式
- 使用 ConditionalOnProperty 注解屏蔽 swaggerconfig 加载
@ConditionalOnProperty( name = {"swagger-enabled"}, havingValue = "true", matchIfMissing = false ) - 通过pom文件中使用 profile 策略
<profiles> <profile> <id>dev</id> <dependencies> </dependencies> </profile> <profile> <id>deploy</id> <dependencies> <dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.1</version> </dependency> </dependencies> </profile> </profiles>
效果
由于引入了Knife4j 前端ui，原始的又没有屏蔽掉，所以有两个访问地址：
-
http://localhost:8080/doc.html#/home
knife4j接口文档.png -
http://localhost:8080/api/swagger-ui.html
api接口文档.png
