3.2 i18n国际化

在Knife4j 2.0.3版本提供了i18n的支持,目前支持的语言主要包含2种：中文(zh-CN)、英文(en-US)。Knife4j默认是中文

那么,如何使用呢?

3.2.1 文档中选择

通过访问doc.html打开文档界面,可以在文档的右上角看到语言的选择,如下图：

直接选择相应的语言版本即可

3.2.2 通过文档地址直接默认i18n

Knife4j也提供了通过地址栏直接将文档显示为指定的语言显示

访问地址规则：

• 中文：http://host:port/doc.html#/home/zh-CN
• 英文：http://host:port/doc.html#/home/en-US

另外,如果你是使用了knife4j提供的增强功能,你也可以这样访问

• 中文：http://host:port/doc.html#/plus/zh-CN
• 英文：http://host:port/doc.html#/plus/en-US

3.2.3 服务端yml配置设定

当然，开发者也可以在后端控制文档语言呈现方式(自2.0.6版本开始)

yml配置如下：

knife4j:
  enable: true
  setting:
    # Knife4j默认显示中文(zh-CN),如果开发者想直接显示英文(en-US)，在通过该配置进行设置即可
    language: zh-CN

在配置文件中进行配置后,还需要在创建Docket对象时，通过调用Knife4j提供的工具对象OpenApiExtensionResolver提供一个OpenAPI的扩展属性结构

示例代码如下：

点击查看代码

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfiguration {

   private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="2.X版本";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //.title("swagger-bootstrap-ui-demo RESTful APIs")
                .description("# swagger-bootstrap-ui-demo RESTful APIs")
                .termsOfServiceUrl("http://www.xx.com/")
                .contact("xx@qq.com")
                .version("1.0")
                .build();
    }
}

通过上面示例代码，主要步骤如下：

1、通过@Autowired注解引入Knife4j向Spring容器注入的Bean对象OpenApiExtensionResolver

2、最终在Dcoket对象构建后，通过调用Docket对象的extensions方法进行插件赋值

3、插件赋值需要调用OpenApiExtensionResolver提供的buildExtensions方法，该方法需要一个逻辑分组名称，就是开发者在yml配置文件中配置的group名称

提示

为什么需要这么做?这样做的目的一方面是充分利用Spring Boot提供的配置方式，方便开发者自定义配置属性，另一方面，通过扩展OpenAPI的规范属性，也更加符合OpenAPI对于扩展属性的要求

OpenAPI规范明确规定,对于扩展属性,开发者应当在响应的某个节点中，增加x-开头的属性方式,以扩展自定义的属性配置

自定义文档的扩展属性，开发者可以通过浏览器的Network功能查看OpenAPI的结构，最终Knife4j扩展增加x-setting属性，代表增加的扩展自定义文档属性，最终在Ui界面解析呈现，结构如下图：

3.2.4 接口、注释、参数全部i18n

如果开发者继续使用的是OpenAPI2规范，自Knife4j 4.0版本，提供了针对接口、参数注释等全部i18n的处理方案

1、引用的starter必须是knfie4j-openapi2-spring-boot-starter组件，openapi3没有此功能 2、示例代码参考knife4j-spring-boot27-demo

第一步，配置开启Spring Boot 框架的i18n功能，增加i18n的配置属性，配置如下：

spring:
 messages:
   basename: i18n/message
   encoding: utf-8
   cache-duration: 3600

第二步,配置新增i18n的配置文件，在src/main/resources目录下，新建i18n/message文件夹,如下图：

第三步，修改代码中的注释配置，代码如下：

@ApiOperation(value = "API_JOB_I18n",notes = "API_JOB_I18n_DESC")
@PostMapping("/hidden3")
public ResponseEntity<ModelUser> i18n3(@RequestBody ModelUser sysUser){
    return ResponseEntity.ok(sysUser);
}

第四步，设置Knife4j提供的增强配置，开发者自行选择是中文还是英文，配置如下：

knife4j:
  enable: true
  setting:
    # Knife4j默认显示中文(zh-CN),如果开发者想直接显示英文(en-US)，在通过该配置进行设置即可
    language: zh-CN