swagger 框架搭建

https://doc.xiaominfo.com/

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案

在使用时，要注意 版本的匹配问题：

Spring Boot版本	Knife4j Swagger2规范	Knife4j OpenAPI3规范
1.5.x~2.0.0	<Knife4j 2.0.0	>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 2.0.6 ~ 2.0.9	>=Knife4j 4.0.0
2.4.0~2.7.x	>=Knife4j 4.0.0	>=Knife4j 4.0.0
>= 3.0	>=Knife4j 4.0.0	>=Knife4j 4.0.0

下面以 springboot 2.7.5 为例

第一步 加入依赖：

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

第二步：创建配置 （这个文件放到项目的 config 目录）

@EnableSwagger2
public class SwaggerConfig  {

    @Bean(value = "default")
    public Docket defaultApi1() {
    //packagePath controller目录 地址 例如 com.xxxx.xxx.web
        String packagePath = this.getClass().getPackage().getName().replace("config","controller");
        Predicate<RequestHandler> requestHandlerPredicate = RequestHandlerSelectors.basePackage(packagePath);
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("1.0版本")
                //.globalOperationParameters(getGlobalOperationParameters())
                .select()
                //这里指定Controller扫描包路径
                .apis(requestHandlerPredicate)
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
//    @Bean(value = "default2")
//    public Docket defaultApi2() {
//        Docket docket=new Docket(DocumentationType.SWAGGER_2)
//                .apiInfo(apiInfo())
//                //分组名称
//                .groupName("工具")
//                //.globalOperationParameters(getGlobalOperationParameters())
//                .select()
//                //这里指定Controller扫描包路径
//                .apis(RequestHandlerSelectors.basePackage("com.xxxx.netplus.main"))
//                .paths(PathSelectors.any())
//                .build();
//        return docket;
//    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxx接口文档")
                .description("xxxx接口文档")
                .termsOfServiceUrl("http://www.xxxx.com/")
                .contact(new Contact("xxxx", "www.xxxx.com", ""))
                .version("1.0")
                .build();
    }

    /**
     * 设置全局参数
     * @return
     */
    private List<Parameter> getGlobalOperationParameters() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        parameterBuilder.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(true);
        pars.add(parameterBuilder.build());
//        parameterBuilder.name("sign").description("数据签名").modelRef(new ModelRef("string")).parameterType("header").required(true);
//        pars.add(parameterBuilder.build());
        return pars;
    }
}

第三步：配置资源路径

/**
 * @Author: ZLL
 */
@Configuration
public class SpringBootConfigurer extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("*").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

第四步：添加快速启动配置（可选）

@SpringBootApplication
@EnableWebMvc
public class TestWebApplication {

    public static void main(String[] args) {
        ConfigurableApplicationContext application = SpringApplication.run(TestWebApplication.class, args);
        initInfo(application);
    }


    public static void initInfo(ConfigurableApplicationContext application){
        Environment env = application.getEnvironment();
        String serverPort = env.getProperty("server.port");
        if (serverPort==null) serverPort = "8080";
        String path = env.getProperty("server.servlet.context-path");
        String name = env.getProperty("spring.application.name");
        name = StringUtils.isEmpty(name) ? "Application" : name;
        String serverName = StringUtils.isEmpty(path) ? "" : path;
        System.out.println("\n----------------------------------------------------------\n\t"
                + name + " is running! Access URLs:\n"
                + "\t本地访问地址: \thttp://localhost:" + serverPort + serverName + "/doc.html\n"
                + "\n---------------------启动完成---------------------");
        //API 文档登录账号密码 配置在对应数据库的YXNET库的interface_user 表  密码由MD5加密，无法解密，只能重置  。
        // 账号 admin  密码 123
//        checkTable();
    }
}

看效果

：

使用方式