本文介绍如何在Linux环境下实现Swagger API文档的国际化（i18n）。我们将逐步讲解如何准备多语言资源文件，配置Swagger以支持国际化，以及在Swagger UI中显示本地化信息。
一、准备多语言资源文件
首先，创建不同语言的资源文件，这些文件通常采用键值对的形式存储，键保持一致，值则为不同语言的翻译。例如：
-
messages_en.properties(英文) -
messages_zh.properties(中文)
文件内容示例：
# messages_en.properties greeting=Hello farewell=Goodbye # messages_zh.properties greeting=你好 farewell=再见
二、使用Spring Boot和Springfox Swagger配置国际化
Swagger本身不支持国际化，但借助Spring Boot和Springfox Swagger可以实现。
-
添加依赖: 在
pom.xml中添加以下依赖：
io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2 org.springframework.boot spring-boot-starter-validation
-
配置国际化: 在Spring Boot配置文件（例如
application.properties或application.yml）中添加国际化配置：
spring:
messages:
basename: i18n/messages
-
创建消息源: 创建一个配置类（例如
InternationalizationConfig），配置消息源：
import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ReloadableResourceBundleMessageSource;
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 InternationalizationConfig implements WebMvcConfigurer {
@Bean
public MessageSource messageSource() {
ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
messageSource.setBasename("classpath:i18n/messages");
messageSource.setDefaultEncoding("UTF-8");
return messageSource;
}
@Bean
public LocaleResolver localeResolver() {
SessionLocaleResolver localeResolver = new SessionLocaleResolver();
localeResolver.setDefaultLocale(Locale.US); // 设置默认语言
return localeResolver;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang"); // URL参数名，用于切换语言
registry.addInterceptor(interceptor);
}
}
-
在Swagger配置中使用国际化: 在Swagger配置类中使用
MessageSource获取本地化消息：
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiInfoBuilder;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.Locale;
@EnableSwagger2
public class SwaggerConfig {
@Autowired
private MessageSource messageSource;
@Bean
public Docket api() {
Locale locale = LocaleContextHolder.getLocale();
String greeting = messageSource.getMessage("greeting", null, locale);
String farewell = messageSource.getMessage("farewell", null, locale);
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("你的包名")) // 替换为你的包名
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo(greeting, farewell));
}
private ApiInfo apiInfo(String greeting, String farewell) {
return new ApiInfoBuilder()
.title("API 文档")
.description("支持国际化的 API 文档")
.version("1.0")
.build();
}
}
三、在Swagger UI中显示本地化消息 (可选，更高级的定制)
Swagger UI本身不直接支持i18n，需要自定义。 这部分通常通过修改Swagger UI的静态文件或使用自定义的JavaScript来实现，这里不再赘述，因为直接在Swagger配置中使用MessageSource已经可以实现基本的国际化。
通过以上步骤，你就可以在Linux环境下为你的Swagger API文档实现国际化了。 记住替换代码中的占位符，例如包名等，以适应你的项目结构。
