Swagger 版本控制

工作中使用Swagger生成接口文档,但是随着版本的迭代,总的接口数量越来越多,而每次版本新增的接口或者修改的接口都会生成到总的文档中,而为了方便按照版本来查看,所以我们就使用Swagger的版本查找

一 定义注解ApiVersion：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ApiVersion {
 
    /**
     * 接口版本号(对应swagger中的group)
     * @return String[]
     */
    String[] group();
 
}

二 定义一个版本号常量

public interface ApiVersionConstant {
    /**
     * 图审系统手机app1.0.0版本
     */
    String FAP_APP100 = "app1.0.0";
 
}
 

三 更改SwaggerConfig添加Docket(可以理解成一组swagger 接口的集合)，并定义groupName,根据ApiVersion的group方法区分不同组(迭代)的接口，代码如下:

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
    
    //默认版本的接口api-docs分组
    @Bean
    public Docket vDefault(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gysoft"))//controller路径
                .paths(PathSelectors.any())
                .build();
    }
    //app1.0.0版本对外接口
    @Bean
    public Docket vApp100(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .groupName(FAP_APP100)
                .select()
                .apis(input -> {
                    ApiVersion apiVersion = input.getHandlerMethod().getMethodAnnotation(ApiVersion.class);
                    if(apiVersion!=null&&Arrays.asList(apiVersion.group()).contains(FAP_APP100)){
                        return true;
                    }
                    return false;
                })//controller路径
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo buildApiInf(){
        return new ApiInfoBuilder()
                .title("接口列表")
                .termsOfServiceUrl("http://127.0.0.1:8080/swagger-ui.html")
                .description("springmvc swagger 接口测试")
                .version("1.0.0")
                .build();
    }
 
}

四 使用

@RestController
@RequestMapping("/document")
@Api(value = "资料文档或者CAD图纸", description = "资料文档或者CAD图纸")
public class DocumentController extends GyBasicSession {
 
    private static final Logger logger = LoggerFactory.getLogger(DocumentController.class);
 
    @ApiImplicitParams({@ApiImplicitParam(name = "page", value = "当前页数", dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "pageSize", value = "每页大小", dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "projectId", value = "项目id", dataType = "string", paramType = "path"),
            @ApiImplicitParam(name = "stageNum", value = "阶段编号", dataType = "string", paramType = "path"),
            @ApiImplicitParam(name = "type", value = "0资料(文档);1cad图纸", dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "searchkey", value = "搜索关键字", dataType = "string", paramType = "query")})
    @ApiOperation("分页获取资料文档(CAD图纸)列表数据")
    @GetMapping("/pageQueryAppDocumentInfo/{page}/{pageSize}/{projectId}/{stageNum}/{type}")
    @ApiVersion(group = ApiVersionConstant.FAP_APP100)
    public PageResult<AppDocumentInfo> pageQueryAppDocumentInfo(@PathVariable Integer page, @PathVariable Integer pageSize, @PathVariable String projectId, @PathVariable String stageNum, @PathVariable Integer type, @RequestParam String searchkey) {
        return null;
    }
 

}

五 效果

image.png