Java--项目引入Swagger、knife4j文档，Swagger配置类设置，Swagger注解介绍

引言

• 在我们项目中，经常需要Swagger生成测试接口文档，方便开发人员对接口进行测试与联调，下面主要讲解如何在项目中启用Swagger与增强的knife4j文档。

引入依赖

• 在项目的pom.xml文件里添加swagger依赖

<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>3.0.2</version>
    </dependency>
</dependencies>

swagger配置类

@Configuration
@EnableSwagger2
@Slf4j
@EnableKnife4j
public class SwaggerConfig  implements ApplicationListener<WebServerInitializedEvent> {
    private SecurityScheme securitySchemes() {
        return new ApiKey("Authorization", "Authorization", "header");
    }
    
    private SecurityContext securityContexts() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build();
    }
    
    // 加入请求头"Authorization"，可以放我们项目生成的token，以进行Spring Security的权限认证
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("xxx", "描述信息");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("Authorization", authorizationScopes));
    }
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .securityContexts(Arrays.asList(securityContexts()))
                .securitySchemes(Arrays.asList(securitySchemes()))
                .apiInfo(new ApiInfoBuilder()
                        .description("接口文档的描述信息")
                        .title("xx项目接口文档")
                        .contact(new Contact("zmx","http://www.javaboy.org","123456789@qq.com"))
                        .version("v1.0")
                        .license("Apache2.0")
                        .build());
    }

    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {

            @Override
            public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
                if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
                    customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                }
                return bean;
            }

            private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
                List<T> copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }

            @SuppressWarnings("unchecked")
            private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                    field.setAccessible(true);
                    return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                } catch (IllegalArgumentException | IllegalAccessException e) {
                    throw new IllegalStateException(e);
                }
            }
        };
    }
    //在项目启动后，控制台输出接口文档访问地址信息
    @Override
    public void onApplicationEvent(WebServerInitializedEvent event) {
        try {
            //获取IP
            String hostAddress = Inet4Address.getLocalHost().getHostAddress();
            log.info("项目启动成功！swagger接口文档地址: http://"+hostAddress+":"+event.getWebServer().getPort()+"/swagger-ui/index.html");
            log.info("项目启动成功！Knife4j接口文档地址: http://"+hostAddress+":"+event.getWebServer().getPort()+"/doc.html");
        } catch (UnknownHostException e) {
            e.printStackTrace();
        }
    }

}

Swagger常用注解

• @Api：用于标注一个Controller，使其能被Swagger扫描解析
• @ApiOperation：用于标注一个Http请求，也就是我们写的接口
• @ApiParam：用于定义请求中的api参数的注解
• @ApiResponses、@ApiResponse：用于定义方法返回对象的描述
• @ApiModel：用于描述模型类的注解
• @ApiModelProperty：用于描述模型类的属性的注解
• 示例：

    @RestController
    @RequestMapping("/xxx")
    @Api(tags = "xx管理", value = "xxController")
    public class xxController {
    
        @Autowired
        private xxService xxService;
        
        @ApiResponses({
    		@ApiResponse(code = 200, message = "请求成功"),
    		@ApiResponse(code = 400, message = "请求参数没填好"),
    		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    	  })
        @ApiOperation(value = "通过id编辑name")
        @PostMapping("edit")
        public Result edit(@RequestParam @ApiParam(name = "id", value = "id") String id,
                           @RequestParam @ApiParam(name = "name", value = "名称") String name) {
            xxService.edit(id, name);
            return Result.ok();
        }
    
    }
    @Data
    @ApiModel(description = "xx查询DTO")
    public class xxQueryDTO {
        @ApiModelProperty(value = "id")
        private String id;
    
        @ApiModelProperty(value = "关键字")
        private String KeyWord;
    }