项目中使用 Swagger 2 和 ApiFox 来管理文档。Swagger 依赖的版本是

• springfox-swagger2：2.9.2
• springfox-swagger-ui：2.9.2

但是更新了 ApiFox 的客户端版本（ 2.2.19 ）后发现：导入时相同路由的接口会自动覆盖。如果只导入一个服务，不会出现接口路由重复的情况。不过若项目中有多个服务，而且碰巧路由重复了，就会出现覆盖别的服务的接口文档的情况。之前的版本导入时可以设置为相同目录下且路由相同时才覆盖，但是新版没有这个设置项。另外数据模型的导入也有类似的问题。

项目使用的 Swagger 3.0 ，依赖如下。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

1. 创建一个 IOperationFilter 的实现

   public class AuthTokenHeaderParameter : IOperationFilter
   {
       public void Apply(Operation operation, OperationFilterContext context)
       {
           operation.Parameters = operation.Parameters ?? new List<IParameter>();
           //MemberAuthorizeAttribute 自定义的身份验证特性标记
           var isAuthor = operation != null && context != null;
           if (isAuthor)
           {
               //in query header
               operation.Parameters.Add(new NonBodyParameter()
               {
                   Name = "Authenticate",
                   In = "header", //query formData ..
                   Description = "身份验证",
                   Required = false,
                   Type = "string"
               });
           }
       }
   }
   

2. 在 Startup.cs 的 ConfigureServices 方法中做些修改

   services.AddSwaggerGen(c =>
   {
       // ...
       c.OperationFilter<AuthTokenHeaderParameter >();
   });
   

在 微服务架构下使用 Spring Cloud Zuul 作为网关将多个微服务整合到一个 Swagger 服务上 讲了如何整合多个服务的 Swagger 到 Zuul 网关上。

例子上的服务是 SpringBoot 的，而我现在的项目中多数是 .NET Core 的微服务。.NET Core 的 Swagger UI 使用的是 Swashbuckle.AspNetCore 3.0.0 。

1. 使用 NuGet 安装 Swashbuckle.AspNetCore 包

   Install-Package Swashbuckle.AspNetCore
   

2. 修改 Startup.cs 文件

   // This method gets called by the runtime. Use this method to add services to the container.
   public void ConfigureServices(IServiceCollection services)
   {
       services.AddMvc();
   
       services.AddSwaggerGen(options =>
       {
           options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
           {
               Version = "v1",
               Title = "My API",
               Description = "by JiaJia"
           });
       });
   }
   
   // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
   public void Configure(IApplicationBuilder app, IHostingEnvironment env)
   {
       if (env.IsDevelopment())
       {
           app.UseDeveloperExceptionPage();
       }
   
       app.UseMvc();
   
   #if DEBUG
       app.UseSwagger();
       app.UseSwaggerUI(c =>
       {
           c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
           // c.DocExpansion(DocExpansion.None);
       });
   #endif
   }
   

3. 访问 Swagger UI 地址 http://localhost:56099/swagger/

4. 显示方法备注。

   现在的 Swagger UI 只会显示接口名，但没有显示备注。如需显示备注，需要

   1. 在项目属性的 生成 => 输出 中勾选 XML 文档文件。

      如： bin\Debug\netcoreapp2.1\Octopus.Cloud.User.xml

   2. 在 Start.cs => ConfigureServices 方法中的 AddSwaggerGen 处增加 IncludeXmlComments 处理。

      services.AddSwaggerGen(options =>
      {
          options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
          {
              Version = "v1",
              Title = "Octopus Cloud API",
              Description = "by Octopus"
          });
      
          options.IncludeXmlComments(string.Format("{0}/Octopus.Cloud.User.xml",
              AppDomain.CurrentDomain.BaseDirectory));
      });
      

   3. 重启之后就可以看到接口方法对应的备注了。

      /// <summary>
      /// 根据 ID 获取用户信息
      /// </summary>
      /// <param name="id">用户 ID</param>
      /// <returns>用户信息</returns>
      [HttpGet("{id}")]
      public ActionResult<string> Get(int id)
      {
          return "user info";
      }
      

1. Pom 文件中添加 Swagger 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>