ASP.NET Core Swashbuckle的使用自定义UI及扩展配置示例

/// 
/// Creates a TodoItem./// 
/// /// Sample request://////     POST /Todo///     {///        "id": 1,///        "name": "Item1",///        "isComplete": true///     }////// /// /// A newly created TodoItem/// Returns the newly created item/// If the item is null            [HttpPost][ProducesResponseType(StatusCodes.Status201Created)][ProducesResponseType(StatusCodes.Status400BadRequest)]public ActionResult Create(TodoItem item){    _context.TodoItems.Add(item);    _context.SaveChanges();    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);}

请注意，UI增强还有以下附加注释：

4､标签字段注解

使用在System.ComponentModel.DataAnnotations命名空间中找到的属性标记模型，以帮助驱动Swagger UI组件。

将[Required]属性添加到类的Name属性中TodoItem：

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; }    }}

此属性的存在会更改UI行为并更改基础的JSON模式：

"definitions": {    "TodoItem": {        "required": [            "name"        ],        "type": "object",        "properties": {            "id": {                "format": "int64",                "type": "integer"            },            "name": {                "type": "string"            },            "isComplete": {                "default": false,                "type": "boolean"            }        }    }},

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

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

该响应内容类型下拉选择此内容类型作为默认控制器的GET操作：

随着Web API中数据注释的使用增加，UI和API帮助页面变得更具描述性和实用性。

5､描述API响应类型

使用Web API的开发人员最关心返回的内容，特别是响应类型和错误代码（如果不是标准的话）。响应类型和错误代码在XML注释和数据注释中表示。

该Create行动在成功时返回一个HTTP 201状态码。当发布的请求正文为null时，返回HTTP 400状态代码。如果在Swagger用户界面中没有适当的文档，则消费者缺乏对这些预期结果的了解。通过在以下示例中添加突出显示的行来解决该问题：

/// 
/// Creates a TodoItem./// 
/// /// Sample request://////     POST /Todo///     {///        "id": 1,///        "name": "Item1",///        "isComplete": true///     }////// /// /// A newly created TodoItem/// Returns the newly created item/// If the item is null            [HttpPost][ProducesResponseType(StatusCodes.Status201Created)][ProducesResponseType(StatusCodes.Status400BadRequest)]public ActionResult Create(TodoItem item){    _context.TodoItems.Add(item);    _context.SaveChanges();    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);}

Swagger UI现在可以清楚地记录预期的HTTP响应代码：

在ASP.NET Core 2.2或更高版本中，可以使用约定代替使用显式装饰单个动作[ProducesResponseType]。有关更多信息，请参阅使用Web API约定。

6､自定义Swashbuckle的UI

库存用户界面既可以使用又可以显示。但是，API文档页面应代表您的品牌或主题。要为Swashbuckle组件打上商标，需要添加资源以提供静态文件，并构建文件夹结构来承载这些文件。

如果定位.NET Framework或.NET Core 1.x，则将Microsoft.AspNetCore.StaticFiles NuGet程序包添加到项目中：

如果定位.NET Core 2.x并使用metapackage，则已经安装了前面的NuGet软件包。

启用静态文件中间件：

public void Configure(IApplicationBuilder app){    app.UseStaticFiles();    // 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");    });    app.UseRouting();    app.UseEndpoints(endpoints =>    {        endpoints.MapControllers();    });}

从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：

浏览至的index.html页面http://localhost:/swagger/ui/index.html。在标题的文本框中输入https://localhost:/swagger/v1/swagger.json，然后单击"Explore"按钮。结果页面如下所示：

相关文档：

ASP.NET Core Web API Swagger/OpenAPI Swashbuckle.AspNetCore NSwag介绍

getting-started-with-swashbuckle

ASP.NET Core Swashbuckle的使用配置及示例