Swashbuckle Swagger在NetCore 3.1中较NetCore 2.2使用的注意事项及入门

背景知识

Swashbuckle 有三个主要组成部分：

Swashbuckle.AspNetCore.Swagger

将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。

Swashbuckle.AspNetCore.SwaggerGen

从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。

Swashbuckle.AspNetCore.SwaggerUI

Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

在NetCore 3中安装

Nuget 安装：Swashbuckle.AspNetCore 建议大于等于5.0版本

将Swagger生成器添加到Startup.ConfigureServices方法中的服务集合中

NetCore 3.1中，原NetCore2.2中的Info已经升级为OpenApiInfo。

基础版本

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

升级版本

主项目生成的地方记得勾选，生成XML，这个用于增强

// 注册Swagger生成器，定义一个和多个Swagger文档
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("https://example.com/license"),
        }
    });

    // Set the comments path for the Swagger JSON and UI.
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

反射用于生成与 Web API 项目相匹配的 XML 文件名。 AppContext.BaseDirectory属性用于构造 XML 文件的路径。 一些 Swagger 功能（例如，输入参数的架构，或各自属性中的 HTTP 方法和响应代码）无需使用 XML 文档文件即可起作用。 对于大多数功能（即方法摘要以及参数说明和响应代码说明），必须使用 XML 文件。

在Startup.Configure方法中，启用中间件为生成的JSON文档和Swagger UI提供服务

基础版本

// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();

// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

升级版本

// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();

// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

    // 要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：
    //c.RoutePrefix = string.Empty;

    // 要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：
    c.RoutePrefix = "doc";
});

扫描二维码关注公众号，回复： 9675908 查看本文章

晋级写法

接口增加描述注释

/// <summary>
/// 获取列表信息
/// </summary>
/// <returns></returns>
[HttpGet]
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

Swagger UI 显示上述代码的<summary>元素的内部文本

接口增加示范说明

/// <summary>
/// 获取列表信息
/// </summary>
/// <remarks>
/// 示例请求:
///
///     GET /Get
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <returns></returns>
[HttpGet]
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

将 元素添加到Get操作方法文档。 它可以补充

元素中指定的信息，并提供更可靠的 Swagger UI。 元素内容可包含文本、JSON 或 XML。

数据模型增加注释

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

        [DefaultValue(false)]
        public bool IsComplete { get; set; }
    }
}

使用System.ComponentModel.DataAnnotations命名空间中的属性来标记模型，以帮助驱动Swagger UI组件。将[Required]属性添加到TodoItem类的Name属性。

申明控制器响应内容类型

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

将[Produces("application/json")]属性添加到API控制器。 这样做的目的是声明控制器的操作支持application/json的响应内容类型。

申明控制动作响应类型

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

使用Web API的开发人员最关心的问题是返回的内容，特别是响应类型和错误代码（如果不标准）。 在 XML注释和数据注释中表示响应类型和错误代码。
Create 操作成功后返回 HTTP 201 状态代码。 发布的请求正文为 NULL 时，将返回 HTTP 400 状态代码。 如果 Swagger UI 中没有提供合适的文档，那么使用者会缺少对这些预期结果的了解。

自定义私有品牌UI

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

API 文档页应代表品牌或主题。 将 Swashbuckle 组件标记为需要添加资源以提供静态文件，并构建文件夹结构以托管这些文件。

从 Swagger UI GitHub 存储库中获取 dist 文件夹的内容。 此文件夹包含 Swagger UI 页必需的资产。
创建 wwwroot/swagger/ui 文件夹，然后将 dist 文件夹的内容复制到其中 。
使用以下 CSS 在 wwwroot/swagger/ui 中创建 custom.css 文件，以自定义页面标题

.swagger-ui .topbar {
    background-color: #000;
    border-bottom: 3px solid #547f00;
}

引用其他 CSS 文件后，引用“ui”文件夹内 index.html 文件中的 custom.css ：

<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css">
<link rel="stylesheet" type="text/css" href="custom.css">

引用资源

Swashbuckle 和 ASP.NET Core 入门