点亮Swagger文档中文展示，打造友好API交互体验

2023-06-30 12:57:38

使用 Swagger 文档化和汉化 .Net Framework Web API

简介

如今，API 已成为构建现代化应用程序的核心。它们使应用程序之间能够轻松通信，交换数据并实现复杂的功能。为了使 API 易于使用并可供开发人员使用，至关重要的是拥有详尽且易于理解的文档。Swagger 是一个流行的开源框架，用于生成交互式 API 文档。它提供了一个简洁且一致的方式来 API 的功能、请求和响应。

本文将指导您逐步在 .Net Framework Web API 中集成 Swagger 并对其文档进行汉化。通过遵循这些步骤，您可以为您的 API 创建高质量的文档，从而提高其可访问性和可用性。

先决条件

安装 .Net Framework 4.5.2 或更高版本
安装 Visual Studio 2017 或更高版本
熟悉 ASP.Net Web API

步骤 1：安装 Swagger.Net 和 Swagger.Net.UI

打开 NuGet 程序包管理器。
搜索并安装 "Swagger.Net" 和 "Swagger.Net.UI"。

这些程序包将为您的项目添加 Swagger 文档生成和用户界面所需的依赖项。

步骤 2：创建 SwaggerControllerDescProvider 类

新建一个名为 "SwaggerControllerDescProvider" 的类。
继承自 "IDocumentFilter" 接口。
重写 "Apply" 方法，对 swagger 文档中的内容进行汉化处理。

public class SwaggerControllerDescProvider : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var apiDescription in context.ApiDescriptions)
        {
            var controllerDesc = apiDescription.ActionDescriptor.ControllerDescriptor;
            var controllerAttributes = controllerDesc.GetCustomAttributes(true);
            var controllerName = controllerDesc.ControllerName;

            if (controllerAttributes.Any(attr => attr is ApiControllerAttribute))
            {
                var controllerTag = swaggerDoc.Tags.FirstOrDefault(tag => tag.Name == controllerName);
                if (controllerTag == null)
                {
                    controllerTag = new Tag { Name = controllerName };
                    swaggerDoc.Tags.Add(controllerTag);
                }

                var apiDescTag = swaggerDoc.Tags.FirstOrDefault(tag => tag.Name == apiDescription.GroupName);
                if (apiDescTag == null)
                {
                    apiDescTag = new Tag { Name = apiDescription.GroupName };
                    swaggerDoc.Tags.Add(apiDescTag);
                }

                var operation = swaggerDoc.Paths[public class SwaggerControllerDescProvider : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var apiDescription in context.ApiDescriptions)
        {
            var controllerDesc = apiDescription.ActionDescriptor.ControllerDescriptor;
            var controllerAttributes = controllerDesc.GetCustomAttributes(true);
            var controllerName = controllerDesc.ControllerName;

            if (controllerAttributes.Any(attr => attr is ApiControllerAttribute))
            {
                var controllerTag = swaggerDoc.Tags.FirstOrDefault(tag => tag.Name == controllerName);
                if (controllerTag == null)
                {
                    controllerTag = new Tag { Name = controllerName };
                    swaggerDoc.Tags.Add(controllerTag);
                }

                var apiDescTag = swaggerDoc.Tags.FirstOrDefault(tag => tag.Name == apiDescription.GroupName);
                if (apiDescTag == null)
                {
                    apiDescTag = new Tag { Name = apiDescription.GroupName };
                    swaggerDoc.Tags.Add(apiDescTag);
                }

                var operation = swaggerDoc.Paths[$"/api/{controllerName}/{apiDescription.RelativePath}"].Get;
                operation.Tags.Add(controllerName);
                operation.Tags.Add(apiDescription.GroupName);
                operation.Summary = apiDescription.HttpMethod + " " + apiDescription.RelativePath;
                operation.Description = apiDescription.HttpMethod + " " + apiDescription.RelativePath;
            }
        }
    }
}
quot;/api/{controllerName}/{apiDescription.RelativePath}"].Get;
                operation.Tags.Add(controllerName);
                operation.Tags.Add(apiDescription.GroupName);
                operation.Summary = apiDescription.HttpMethod + " " + apiDescription.RelativePath;
                operation.Description = apiDescription.HttpMethod + " " + apiDescription.RelativePath;
            }
        }
    }
}

这个类负责为 Swagger 文档中的控制器和操作添加中文。

步骤 3：创建 swagger_lang.js 文件

在 SwaggerUI 文件夹中创建一个名为 "swagger_lang.js" 的文件。
将以下代码复制到该文件中：

window.swaggerUi = window.swaggerUi || {};
window.swaggerUi.i18n = window.swaggerUi.i18n || {};
window.swaggerUi.i18n.resourceBundle = {
  "loading": "加载中...",
  "failedToLoadRes": "加载资源失败",
  "noApi": "没有 API 文档。",
  "endpoints": "端点",
  "schemes": "方案",
  "protocols": "协议",
  "gettingStarted": "开始使用",
  "onlineDocs": "在线文档",
  "formatLabel": "格式：",
  "filterLabel": "筛选：",
  "showCommon": "展示通用",
  "common": "通用",
  "explore": "探索",
  "operations": "操作",
  "parameters": "参数",
  "requestHeaders": "请求头",
  "requestBody": "请求体",
  "responseHeaders": "响应头",
  "responseBody": "响应体",
  "parametersGroup": "参数组",
  "headerName": "头名称",
  "headerValue": "头值",
  "parameterName": "参数名称",
  "parameterDescription": "参数",
  "parameterType": "参数类型",
  "parameterDefault": "参数默认值",
  "consumes": "消耗",
  "produces": "产生",
  "requestBodyDescription": "请求体",
  "requestRequired": "必需",
  "responseMessages": "响应消息",
  "statusCode": "状态码",
  "reason": "原因",
  "example": "示例值",
  "allowTryItOut": "允许尝试",
  "tryItOutFailed": "尝试失败",
  "tryItOutEnabled": "尝试已启用",
  "value": "值",
  "externalDocs": "外部文档",
  "useFullResponse": "使用完整响应",
  "url": "URL",
  "securityDefinitions": "安全定义",
  "apiKey": "API 密钥",
  "keyName": "密钥名称",
  "keyIn": "密钥位置",
  "name": "名称",
  "in": "位置",
  "description": "描述",
  "required": "必需",
  " схемы ": "架构",
  "schema": "架构",
  "schemaProperties": "架构属性",
  "property": "属性",
  "type": "类型"
};

这个文件包含 Swagger UI 的汉化资源包。

步骤 4：修改 swagger_lang.js 文件属性

将 swagger_lang.js 文件的生成操作修改为 "嵌入的资源"。

这将确保该文件被编译到您的应用程序中。

步骤 5：在 SwaggerConfig 类中注册 SwaggerControllerDescProvider 类

在 SwaggerConfig 类中，注册 SwaggerControllerDescProvider 类。

public static class SwaggerConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.EnableSwagger(c =>
        {
            c.DocumentFilter<SwaggerControllerDescProvider>();
        })
        .EnableSwaggerUi(c =>
        {
            c.InjectJavaScript(Assembly.GetExecutingAssembly(), "Swagger.Net.UI.swagger_lang.js");
        });
    }
}