概述

silky 框架通过 Silky.Http.Swagger 模块集成了 Swagger/OpenAPI 文档能力，使前端开发者能够通过可视化界面浏览和调试所有对外暴露的 RPC 接口。

与传统 ASP.NET Core Swagger 不同，silky 的 Swagger 文档来源于注册中心——框架将所有微服务的 IApplicationService 服务条目聚合到网关，并在网关的 Swagger UI 中集中展示。这意味着开发者只需访问网关的 Swagger 页面，即可看到整个微服务系统的所有接口文档。

注册服务

在网关 Startup.cs 中启用 Swagger：

public void ConfigureServices(IServiceCollection services)
{
    services.AddSilkyHttpCore()
        .AddSwaggerDocuments();    // 注册 Swagger 文档服务

    services.AddRouting();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    app.UseSwaggerDocuments();     // 启用 Swagger 中间件（含 SwaggerUI）

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapSilkyRpcServices();
    });
}

UseSwaggerDocuments() 同时调用了 UseSwagger()（提供 OpenAPI JSON 端点）和 UseSwaggerUI()（提供可视化页面），只需一行代码即可完整启用。

配置项说明

Swagger 文档通过 SwaggerDocument 配置节点进行配置，对应类型为 SwaggerDocumentOptions：

OrganizationMode（文档组织方式）

ShowMode（服务显示模式）

配置示例

基础配置（适合大多数项目）

SwaggerDocument:
  title: "我的微服务平台 API"
  description: "提供订单、账户、商品等业务接口"
  version: "v1.0"
  enableAuthorized: true
  organizationMode: AllAndGroup

启用 XML 注释

要在 Swagger UI 中显示接口注释，需要：

步骤一：在 .csproj 中启用 XML 文档生成：

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

步骤二：在配置文件中指定 XML 注释文件名：

SwaggerDocument:
  title: "我的 API"
  xmlComments:
    - "MyApp.Application.Contracts.xml"
    - "MyApp.Domain.Shared.xml"

自定义分组

Group/AllAndGroup 模式下，框架会自动按微服务名称分组。也可通过 groups 配置进行自定义分组：

SwaggerDocument:
  organizationMode: AllAndGroup
  groups:
    - applicationInterface: IOrderAppService
      title: 订单接口
      version: v1.0
    - applicationInterface: IInventoryAppService
      title: 库存接口
      version: v1.0

关闭认证按钮（仅限内部系统）

SwaggerDocument:
  enableAuthorized: false

指定 UI 路由前缀

SwaggerDocument:
  routePrefix: "swagger"   # Swagger UI 访问路径变为 /swagger

JWT 认证集成

当 enableAuthorized: true（默认）时，Swagger UI 右上角会出现 Authorize 按钮。点击后输入 JWT Token：

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

之后所有请求会自动在 Authorization Header 中携带此 Token。

配合 silky 身份认证模块（Silky.Http.Identity），网关会自动验证 Token 并将用户信息注入 RpcContext，无需为每个接口单独处理认证逻辑。

访问 Swagger UI

默认配置下，Swagger UI 可以通过以下地址访问：

• 开发环境：http://localhost:端口/index.html（routePrefix 为空时）
• 配置了前缀：http://localhost:端口/swagger/index.html

OpenAPI JSON 数据端点：http://localhost:端口/swagger/v1/swagger.json

if (env.IsDevelopment())
{
    app.UseSwaggerDocuments();
}