0
点赞
收藏
分享

微信扫一扫

教你一步一步集成swagger

在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,原始的又没有屏蔽掉,所以有两个访问地址:

举报

相关推荐

0 条评论