feat: 新增 API 文档（Knife4j：Spring Doc）自动配置

continew-starter-api-doc/pom.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>top.charles7c.continew</groupId>
+        <artifactId>continew-starter</artifactId>
+        <version>${revision}</version>
+    </parent>
+
+    <artifactId>continew-starter-api-doc</artifactId>
+    <packaging>jar</packaging>
+
+    <name>${project.artifactId}</name>
+    <description>ContiNew Starter API 文档模块</description>
+
+    <dependencies>
+        <!-- Knife4j（前身是 swagger-bootstrap-ui，集 Swagger2 和 OpenAPI3 为一体的增强解决方案） -->
+        <dependency>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+        </dependency>
+
+        <!-- 核心模块 -->
+        <dependency>
+            <groupId>top.charles7c.continew</groupId>
+            <artifactId>continew-starter-core</artifactId>
+        </dependency>
+    </dependencies>
+</project>

continew-starter-api-doc/src/main/java/top/charles7c/continew/starter/apidoc/autoconfigure/SpringDocAutoConfiguration.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2022-present Charles7c Authors. All Rights Reserved.
+ * <p>
+ * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE 3.0;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.gnu.org/licenses/lgpl.html
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package top.charles7c.continew.starter.apidoc.autoconfigure;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import jakarta.annotation.PostConstruct;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Lazy;
+import top.charles7c.continew.starter.core.autoconfigure.ProjectProperties;
+
+/**
+ * API 文档自动配置
+ *
+ * @author Charles7c
+ * @since 1.0.0
+ */
+@Slf4j
+@Lazy
+@Configuration(proxyBeanMethods = false)
+@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", havingValue = "true")
+public class SpringDocAutoConfiguration {
+
+    /**
+     * Open API 配置
+     */
+    @Bean
+    @ConditionalOnMissingBean
+    public OpenAPI openApi(ProjectProperties properties) {
+        Info info = new Info()
+                .title(String.format("%s %s", properties.getName(), "API 文档"))
+                .version(properties.getVersion())
+                .description(properties.getDescription());
+        ProjectProperties.Contact contact = properties.getContact();
+        if (null != contact) {
+            info.contact(new Contact().name(contact.getName())
+                    .email(contact.getEmail())
+                    .url(contact.getUrl()));
+        }
+        ProjectProperties.License license = properties.getLicense();
+        if (null != license) {
+            info.license(new License().name(license.getName())
+                    .url(license.getUrl()));
+        }
+        return new OpenAPI().info(info);
+    }
+
+    @PostConstruct
+    public void postConstruct() {
+        log.info("[ContiNew Starter] - Auto Configuration 'ApiDoc' completed initialization.");
+    }
+}

continew-starter-api-doc/src/main/java/top/charles7c/continew/starter/apidoc/autoconfigure/StaticResourceAutoConfiguration.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2022-present Charles7c Authors. All Rights Reserved.
+ * <p>
+ * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE 3.0;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.gnu.org/licenses/lgpl.html
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package top.charles7c.continew.starter.apidoc.autoconfigure;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.CacheControl;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * 静态资源处理器自动配置
+ *
+ * @author Charles7c
+ * @since 1.0.0
+ */
+@EnableWebMvc
+@Configuration(proxyBeanMethods = false)
+@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", havingValue = "true")
+public class StaticResourceAutoConfiguration implements WebMvcConfigurer {
+
+    @Override
+    public void addResourceHandlers(ResourceHandlerRegistry registry) {
+        registry.addResourceHandler("/favicon.ico").addResourceLocations("classpath:/");
+        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
+        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/")
+            .setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());
+    }
+}

continew-starter-api-doc/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1,2 @@
+top.charles7c.continew.starter.apidoc.autoconfigure.SpringDocAutoConfiguration
+top.charles7c.continew.starter.apidoc.autoconfigure.StaticResourceAutoConfiguration

continew-starter-core/src/main/java/top/charles7c/continew/starter/core/autoconfigure/ProjectProperties.java

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 2022-present Charles7c Authors. All Rights Reserved.
+ * <p>
+ * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE 3.0;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.gnu.org/licenses/lgpl.html
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package top.charles7c.continew.starter.core.autoconfigure;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import org.springframework.stereotype.Component;
+
+/**
+ * 项目配置属性
+ *
+ * @author Charles7c
+ * @since 1.0.0
+ */
+@Data
+@Component
+@ConfigurationProperties(prefix = "project")
+public class ProjectProperties {
+
+    /**
+     * 名称
+     */
+    private String name;
+
+    /**
+     * 应用名称
+     */
+    private String appName;
+
+    /**
+     * 版本
+     */
+    private String version;
+
+    /**
+     * 描述
+     */
+    private String description;
+
+    /**
+     * URL
+     */
+    private String url;
+
+    /**
+     * 基本包
+     */
+    private String basePackage;
+
+    /**
+     * 联系人
+     */
+    @NestedConfigurationProperty
+    private Contact contact;
+
+    /**
+     * 许可协议
+     */
+    @NestedConfigurationProperty
+    private License license;
+
+    /**
+     * 是否为生产环境
+     */
+    private boolean production = false;
+
+    /**
+     * 联系人配置属性
+     */
+    @Data
+    public static class Contact {
+        /**
+         * 名称
+         */
+        private String name;
+
+        /**
+         * 邮箱
+         */
+        private String email;
+
+        /**
+         * URL
+         */
+        private String url;
+    }
+
+    /**
+     * 许可协议配置属性
+     */
+    @Data
+    public static class License {
+        /**
+         * 名称
+         */
+        private String name;
+
+        /**
+         * URL
+         */
+        private String url;
+    }
+}

continew-starter-dependencies/pom.xml

@@ -55,11 +55,21 @@
 
     <properties>
         <revision>1.0.0-SNAPSHOT</revision>
+        <knife4j.version>4.3.0</knife4j.version>
         <hutool.version>5.8.23</hutool.version>
     </properties>
 
     <dependencyManagement>
         <dependencies>
+            <!-- Knife4j（前身是 swagger-bootstrap-ui，集 Swagger2 和 OpenAPI3 为一体的增强解决方案） -->
+            <dependency>
+                <groupId>com.github.xiaoymin</groupId>
+                <artifactId>knife4j-dependencies</artifactId>
+                <version>${knife4j.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+
             <!-- Hutool（小而全的 Java 工具类库，通过静态方法封装，降低相关 API 的学习成本，提高工作效率，使 Java 拥有函数式语言般的优雅，让 Java 语言也可以“甜甜的”） -->
             <dependency>
                 <groupId>cn.hutool</groupId>
@@ -67,6 +77,13 @@
                 <version>${hutool.version}</version>
             </dependency>
 
+            <!-- API 文档模块 -->
+            <dependency>
+                <groupId>top.charles7c.continew</groupId>
+                <artifactId>continew-starter-api-doc</artifactId>
+                <version>${revision}</version>
+            </dependency>
+
             <!-- Jackson 模块 -->
             <dependency>
                 <groupId>top.charles7c.continew</groupId>

pom.xml

@@ -70,6 +70,7 @@
         <module>continew-starter-dependencies</module>
         <module>continew-starter-core</module>
         <module>continew-starter-json</module>
+        <module>continew-starter-api-doc</module>
     </modules>
 
     <dependencies>