在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();
}

最后将前端资源所在的路径告知 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访问有两种方式

1. 使用 ConditionalOnProperty 注解屏蔽 swaggerconfig 加载

   @ConditionalOnProperty(
       name = {"swagger-enabled"},
       havingValue = "true",
       matchIfMissing = false
   )
   

2. 通过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
  

  

• http://localhost:8080/api/swagger-ui.html