Debian系统支持Swagger多语言的核心思路
在Debian环境中，Swagger（现称OpenAPI）的多语言支持主要通过资源文件管理、框架集成（如Spring Boot）和前端展示调整实现。以下是具体步骤：
创建不同语言的资源文件（如.properties、.json、.yaml），以键值对形式存储翻译文本。例如：
messages_en.properties（英文）：swagger.title=API Documentation
swagger.description=This is the API documentation for our application.
messages_zh_CN.properties（中文）：swagger.title=API文档
swagger.description=这是我们应用程序的API文档。
资源文件需统一存放在项目目录（如src/main/resources/i18n/），便于后续加载。
若使用Spring Boot框架，需配置MessageSource Bean来加载资源文件。在配置类中添加以下代码：
import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ReloadableResourceBundleMessageSource;
@Configuration
public class InternationalizationConfig {
@Bean
public MessageSource messageSource() {
ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
messageSource.setBasename("classpath:i18n/messages"); // 资源文件基路径
messageSource.setDefaultEncoding("UTF-8"); // 支持中文等非ASCII字符
messageSource.setUseCodeAsDefaultMessage(true); // 未找到翻译时使用key
return messageSource;
}
}
此配置会自动加载i18n目录下的所有语言资源文件。
使用Springdoc OpenAPI的@Operation注解，结合MessageSource动态获取翻译文本。例如：
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Locale;
@RestController
public class ApiController {
@Autowired
private MessageSource messageSource;
@Operation(summary = "#{swagger.summary}", description = "#{swagger.description}")
@GetMapping("/api/resource")
public String getResource() {
return "Resource data";
}
}
需配合springdoc-openapi-starter-webmvc-ui依赖（版本≥2.1.0），并通过MessageSource解析注解中的SpEL表达式。
在Swagger配置类中，直接引用资源文件的值。例如：
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Locale;
@Configuration
public class SwaggerConfig {
@Autowired
private MessageSource messageSource;
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title(messageSource.getMessage("swagger.title", null, Locale.getDefault()))
.description(messageSource.getMessage("swagger.description", null, Locale.getDefault()))
.version("1.0.0"));
}
}
此方式适用于静态文档，语言切换需重启应用。
通过URL参数传递语言偏好（如?lang=zh），在后端拦截请求并设置Locale。例如：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
import org.springframework.web.servlet.i18n.SessionLocaleResolver;
import java.util.Locale;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Bean
public LocaleResolver localeResolver() {
SessionLocaleResolver resolver = new SessionLocaleResolver();
resolver.setDefaultLocale(Locale.US); // 默认语言
return resolver;
}
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang"); // URL参数名（如?lang=zh）
return interceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeChangeInterceptor()); // 注册拦截器
}
}
访问http://localhost:8080/swagger-ui.html?lang=zh即可切换至中文文档。
若需根据请求头（如Accept-Language）自动切换语言，可配置RequestLocalizationOptions（适用于Spring Boot）：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
import org.springframework.web.servlet.i18n.SessionLocaleResolver;
import java.util.Locale;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Bean
public LocaleResolver localeResolver() {
SessionLocaleResolver resolver = new SessionLocaleResolver();
resolver.setDefaultLocale(Locale.US);
return resolver;
}
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang");
return interceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeChangeInterceptor());
}
}
此配置会自动检测请求头的Accept-Language字段，优先匹配支持的语言（如zh-CN）。
将应用部署到Debian服务器（如Tomcat、Spring Boot内置服务器），启动后访问Swagger UI（如http://localhost:8080/swagger-ui.html）。通过URL参数或浏览器语言设置切换语言，验证翻译是否正确显示。
注意事项：
ReloadableResourceBundleMessageSource替换为MessageSourceAutoConfiguration；i18next等前端库，但需额外配置。
