如何实现OpenAPI3 API文档的多语言本地化（含Swagger UI场景）

Awesome question! Let’s walk through how to add multi-language support (like English and Russian) to your OpenAPI 3 docs, especially since you’re using Swagger UI. There are both community-endorsed standard approaches and flexible custom options depending on your team’s workflow.

OpenAPI 3 doesn’t have a built-in native i18n system, but the community has settled on two widely accepted patterns:

a. Separate OpenAPI Documents Per Language #

This is the most straightforward "standard" method. You maintain full copies of your OpenAPI spec for each language—for example, openapi-en.json (your existing English version) and openapi-ru.json (the translated Russian version).

How to use with Swagger UI: #

• Add a language switcher (like a dropdown) to your Swagger UI page. When a user selects Russian, use Swagger UI’s JavaScript API to reload the spec with the Russian file:

  // Example: Initialize Swagger UI with English spec
  const ui = SwaggerUIBundle({
    url: "openapi-en.json",
    dom_id: "#swagger-ui",
    // ... other config options
  });
  
  // Add click handler for language switch button
  document.getElementById("switch-to-ru").addEventListener("click", () => {
    ui.specUrl = "openapi-ru.json";
    ui.loadSpec();
  });
  

• Pros: Fully compliant with OpenAPI specs, no custom code needed for Swagger UI’s core rendering.
• Cons: Requires syncing changes across all language files—if you update an endpoint’s structure, you’ll need to apply that change to every translated spec.

b. OpenAPI Custom Extensions for Multi-Language Fields #

OpenAPI allows custom fields prefixed with x-, so you can embed translated content directly in your single spec file. For example:

openapi: 3.0.3
info:
  title: User API
  x-title-ru: API Пользователей
  description: Manage user accounts
  x-description-ru: Управление учетными записями пользователей
paths:
  /users:
    get:
      summary: List all users
      x-summary-ru: Список всех пользователей
      description: Retrieve a paginated list of registered users
      x-description-ru: Получить страничный список зарегистрированных пользователей

How to use with Swagger UI: #

You’ll need to tweak Swagger UI’s rendering logic to check for and display the translated fields when a language is selected. This can be done via a custom plugin or by modifying the Swagger UI source code (if you’re self-hosting).

• Pros: Only one spec file to maintain—structure changes only need to be made once.
• Cons: Requires custom code to handle the extension fields, but this is a widely accepted use of OpenAPI’s extension mechanism.

If you want to avoid repetitive manual translations or syncing multiple files, community tools can help:

• Localization Generators: Tools like openapi-i18n let you define translations in a separate JSON/YAML file (e.g., translations-ru.json) and auto-generate the full Russian OpenAPI spec from your original English file.
• Swagger UI Plugins: Some third-party plugins pre-build the language switcher logic, so you just need to add your translated extension fields or point to your multi-language spec files.

If the above approaches don’t fit your needs, you can build a lightweight custom system:

1. Store translations in a dedicated structure: Embed a multi-language object using an extension like x-i18n in your spec:

   paths:
     /users:
       get:
         x-i18n:
           en:
             summary: List all users
             description: Retrieve a paginated list of registered users
           ru:
             summary: Список всех пользователей
             description: Получить страничный список зарегистрированных пользователей
   

2. Add a language switcher: In your Swagger UI setup, add a button/dropdown that triggers a function to traverse the spec object and replace summary/description fields with the selected language’s content from x-i18n.
3. Externalize translations: For easier management, move the x-i18n content to separate JSON files (e.g., i18n-en.json, i18n-ru.json) and inject them into the spec when loading Swagger UI.

• If your API changes infrequently and your team is small, go with separate per-language specs—it’s low-effort and avoids custom code.
• If your API evolves often, use extension fields + a localization generator to keep maintenance overhead low.

内容的提问来源于stack exchange，提问作者Frank59