knife4j 替代swagger2接口文档管理

青旅半醒 2022-09-12 10:52 245阅读 0赞

### 1 引入依赖 ###

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

### 2 application.yml 配置 访问根路径 ###

swagger2-path: /${ spring.application.name}

### 3 Swagger2Config.java ###

/* * Copyright 2021 Wicrenet, Inc. All rights reserved. */
    package com.hq.cloud.rfid.base.config;
    
    import org.apache.commons.lang3.StringUtils;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.autoconfigure.AutoConfigureAfter;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.core.env.Environment;
    import org.springframework.core.io.ClassPathResource;
    import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping;
    import org.springframework.web.servlet.resource.PathResourceResolver;
    import org.springframework.web.servlet.resource.ResourceHttpRequestHandler;
    import org.springframework.web.util.UrlPathHelper;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import javax.servlet.ServletContext;
    import java.util.Collections;
    import java.util.HashMap;
    import java.util.Map;
    
    /** * Swagger2 前端API配置 * * @author yangjunxiong * @date 2021/9/23 16:45 **/
    @Configuration
    @EnableSwagger2
    @AutoConfigureAfter({ WebMvcConfg.class})
    public class Swagger2Config { 
        private final Environment environment;
        private final String      swagger2Path;
    
        public Swagger2Config(Environment environment, @Value("${swagger2-path}") String swagger2Path) { 
            this.environment = environment;
            this.swagger2Path = swagger2Path;
        }
    
        @Bean
        public Docket createRestApi() { 
            boolean swagger2Show = true;
            //生产关闭swagger2
            if (StringUtils.equals(environment.getActiveProfiles()[0], "prod")) { 
                swagger2Show = false;
            }
            return new Docket(DocumentationType.SWAGGER_2)
                    .enable(swagger2Show)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.hq.cloud.rfid"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("xxx项目API接口管理")
                    .contact(new Contact("xxx", "", ""))
                    .version("1.0.0")
                    .build();
        }
    
        /** * SwaggerUI资源访问 */
        @Bean
        public SimpleUrlHandlerMapping swaggerUrlHandlerMapping(ServletContext servletContext,
                                                                @Value("${swagger.mapping.order:10}") int order) throws Exception { 
            SimpleUrlHandlerMapping urlHandlerMapping = new SimpleUrlHandlerMapping();
            Map<String, ResourceHttpRequestHandler> urlMap = new HashMap<>();
            { 
                PathResourceResolver pathResourceResolver = new PathResourceResolver();
                pathResourceResolver.setAllowedLocations(new ClassPathResource("META-INF/resources/webjars/"));
                pathResourceResolver.setUrlPathHelper(new UrlPathHelper());
    
                ResourceHttpRequestHandler resourceHttpRequestHandler = new ResourceHttpRequestHandler();
                resourceHttpRequestHandler.setLocations(Collections.singletonList(new ClassPathResource("META-INF/resources/webjars/")));
                resourceHttpRequestHandler.setResourceResolvers(Collections.singletonList(pathResourceResolver));
                resourceHttpRequestHandler.setServletContext(servletContext);
                resourceHttpRequestHandler.afterPropertiesSet();
                urlMap.put(swagger2Path + "/webjars/**", resourceHttpRequestHandler);
            }
            { 
                PathResourceResolver pathResourceResolver = new PathResourceResolver();
                pathResourceResolver.setAllowedLocations(new ClassPathResource("META-INF/resources/"));
                pathResourceResolver.setUrlPathHelper(new UrlPathHelper());
    
                ResourceHttpRequestHandler resourceHttpRequestHandler = new ResourceHttpRequestHandler();
                resourceHttpRequestHandler.setLocations(Collections.singletonList(new ClassPathResource("META-INF/resources/")));
                resourceHttpRequestHandler.setResourceResolvers(Collections.singletonList(pathResourceResolver));
                resourceHttpRequestHandler.setServletContext(servletContext);
                resourceHttpRequestHandler.afterPropertiesSet();
                urlMap.put(swagger2Path + "/**", resourceHttpRequestHandler);
            }
            urlHandlerMapping.setUrlMap(urlMap);
            urlHandlerMapping.setOrder(order);
            return urlHandlerMapping;
        }
    
    }

### 4 SwaggerResourceController.java ###

package com.hq.cloud.rfid.controller;
    
    import org.springframework.beans.factory.InitializingBean;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.http.ResponseEntity;
    import org.springframework.plugin.core.PluginRegistry;
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.ResponseBody;
    import org.springframework.web.servlet.ModelAndView;
    import springfox.documentation.annotations.ApiIgnore;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.DocumentationCache;
    import springfox.documentation.spring.web.json.Json;
    import springfox.documentation.spring.web.json.JsonSerializer;
    import springfox.documentation.swagger.web.ApiResourceController;
    import springfox.documentation.swagger.web.SecurityConfiguration;
    import springfox.documentation.swagger.web.SwaggerResource;
    import springfox.documentation.swagger.web.UiConfiguration;
    import springfox.documentation.swagger2.mappers.ServiceModelToSwagger2Mapper;
    import springfox.documentation.swagger2.web.Swagger2ControllerWebMvc;
    import springfox.documentation.swagger2.web.WebMvcSwaggerTransformationFilter;
    
    import javax.servlet.http.HttpServletRequest;
    import java.util.List;
    
    import static org.springframework.util.MimeTypeUtils.APPLICATION_JSON_VALUE;
    
    /** * SwaggerUI接口访问 */
    @Controller
    @ApiIgnore
    @RequestMapping("{swagger2-path}")
    public class SwaggerResourceController implements InitializingBean { 
        public final         String                                                               swagger2Path;
        private final        ApiResourceController                                                apiResourceController;
        private final        DocumentationCache                                                   documentationCache;
        private final        ServiceModelToSwagger2Mapper                                         mapper;
        private final        JsonSerializer                                                       jsonSerializer;
        private final        PluginRegistry<WebMvcSwaggerTransformationFilter, DocumentationType> transformations;
        private static final String                                                               HAL_MEDIA_TYPE = "application/hal+json";
        private              Swagger2ControllerWebMvc                                             swagger2ControllerWebMvc;
    
        public SwaggerResourceController(@Value("${swagger2-path}") String swagger2Path, ApiResourceController apiResourceController, DocumentationCache documentationCache, ServiceModelToSwagger2Mapper mapper, JsonSerializer jsonSerializer, PluginRegistry<WebMvcSwaggerTransformationFilter, DocumentationType> transformations) { 
            this.swagger2Path = swagger2Path;
            this.apiResourceController = apiResourceController;
            this.documentationCache = documentationCache;
            this.mapper = mapper;
            this.jsonSerializer = jsonSerializer;
            this.transformations = transformations;
        }
    
        @Override
        public void afterPropertiesSet() { 
            swagger2ControllerWebMvc = new Swagger2ControllerWebMvc(documentationCache, mapper, jsonSerializer, transformations);
        }
    
        /** * Swagger API首页地址 * @return 首页地址 */
        @RequestMapping
        public ModelAndView index() { 
            return new ModelAndView("redirect:" + swagger2Path + "/doc.html");
        }
    
        @RequestMapping("/swagger-resources/configuration/security")
        @ResponseBody
        public ResponseEntity<SecurityConfiguration> securityConfiguration() { 
            return apiResourceController.securityConfiguration();
        }
    
        @RequestMapping("/swagger-resources/configuration/ui")
        @ResponseBody
        public ResponseEntity<UiConfiguration> uiConfiguration() { 
            return apiResourceController.uiConfiguration();
        }
    
        @RequestMapping("/swagger-resources")
        @ResponseBody
        public ResponseEntity<List<SwaggerResource>> swaggerResources() { 
            return apiResourceController.swaggerResources();
        }
    
        @RequestMapping(value = "/v2/api-docs", method = RequestMethod.GET, produces = { APPLICATION_JSON_VALUE, HAL_MEDIA_TYPE})
        @ResponseBody
        public ResponseEntity<Json> getDocumentation(
                @RequestParam(value = "group", required = false) String swaggerGroup,
                HttpServletRequest servletRequest) { 
            return swagger2ControllerWebMvc.getDocumentation(swaggerGroup, servletRequest);
        }
    }

### 访问路径 项目跟路径就是第2步 application.yml 配置 ###

ip:端口号/项目根路径/doc.htm