c# webapi 配置swagger的方法

接下来我将为你详细讲解如何配置Swagger来生成C# Web API文档的步骤和示例。

配置Swagger的方法

步骤一：安装Swagger

首先，你需要通过NuGet安装以下两个软件包：Swashbuckle.AspNetCore和Swashbuckle.AspNetCore.Annotations。 安装方式如下：

Install-Package Swashbuckle.AspNetCore
Install-Package Swashbuckle.AspNetCore.Annotations

步骤二：添加Swagger到API

在同一个文件夹下创建Swagger配置文件，名为SwaggerConfig.cs，以下是配置文件的基本结构：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;

public static class SwaggerConfig
{
  public static void AddSwaggerGen(SwaggerGenOptions options)
  {

  }

  public static void AddSwaggerUI(this IApplicationBuilder app)
  {

  }
}

步骤三：配置Swagger

在SwaggerConfig.cs中，我们需要设置以下Swagger配置：

添加Swagger服务

在ConfigureServices方法中，添加以下代码：

public static void ConfigureServices(IServiceCollection services)
{
  services.AddSwaggerGen(options =>
  {
    options.SwaggerDoc("v1", new Info { Title = "Your API Title", Version = "v1" });
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourXmlDoc.xml"));
  });
}

其中，Title代表API的名称，Version代表API的版本，IncludeXmlComments则是引用XML注释文档，以便Swagger能够正确显示API的描述和参数说明。

配置Swagger UI

在AddSwaggerUI()方法中，添加以下代码：

public static void AddSwaggerUI(this IApplicationBuilder app)
{
  app.UseSwaggerUI(options =>
  {
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Title");
  });
}

其中，SwaggerEndpoint表示swagger.json文件在API中的位置，以下示例说明如何使用Swagger UI：

app.UseSwaggerUI(options =>
{
  options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
  options.RoutePrefix = string.Empty;
});

注： 在RoutePrefix这里配置为空字符串时，会将Swagger UI限制为API的根路径。如果您愿意，可以自己选择一个不同的路径。

步骤四：启动Swagger

在Startup.cs中的Configure()方法中添加以下代码：

app.UseSwagger();
app.UseSwaggerUI();

现在，你已经完成了Swagger的配置，可以通过URI /swagger访问Swagger UI。

示例

示例一：获取用户列表

以下为一个用做获取用户列表的控制器：

public class UserController : Controller
{
    [HttpGet("users")]
    public ActionResult<IList<User>> GetUsers()
    {
      return new List<User>
      {
          new User { Id = 1, Name = "Alice" },
          new User { Id = 2, Name = "Bob" },
          new User { Id = 3, Name = "Charlie" }
      };
    }
}

可添加Swagger注释来描述方法：

public class UserController : Controller
{
    /// <summary>
    /// 获取所有用户
    /// </summary>
    /// <response code="200">成功获取所有用户</response>
    [HttpGet("users")]
    public ActionResult<IList<User>> GetUsers()
    {
        return new List<User>
        {
            new User { Id = 1, Name = "Alice" },
            new User { Id = 2, Name = "Bob" },
            new User { Id = 3, Name = "Charlie" }
        };
    }
}

添加注释之后，你就可以通过Swagger UI发现新的API细节，包括请求参数、响应代码、请求body以及API的描述性信息。

示例二：添加用户

以下为一个用作添加用户的控制器：

public class UserController : Controller
{
    [HttpPost("users")]
    public ActionResult AddUser([FromBody] User user)
    {
        //DO SOMETHING
        return Ok();
    }
}

添加Swagger注释以描述方法的使用：

public class UserController : Controller
{
    /// <summary>
    /// 添加用户
    /// </summary>
    /// <param name="user"></param>
    /// <response code="200">用户添加成功</response>
    [HttpPost("users")]
    public ActionResult AddUser([FromBody] User user)
    {
        //DO SOMETHING
        return Ok();
    }
}

到此为止，你已经了解到如何在C# WebAPI中配置Swagger并且实现简单的API操作。