1、配置添加命名空间
在Startup
该类中,添加以下名称空间:
using System;
using System.Reflection;
using System.IO;
2、API信息和说明
传递给该AddSwaggerGen
方法的配置操作会添加诸如作者,许可证和描述之类的信息:
// 注册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"),
}
});
});
Swagger UI显示版本信息:
3、配置XML注释
可以使用以下方法启用XML注释:
1) 在解决方案资源管理器中右键单击该项目,然后选择Edit <project_name>.csproj
。
2) 手动将显示的行添加到.csproj
文件:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
启用XML注释可为未公开的公共类型和成员提供调试信息。警告消息指示未记录的类型和成员。例如,以下消息表示违反警告代码1591:
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'
要在项目范围内禁止显示警告,请在项目文件中定义要用分号分隔的警告代码列表。附加警告代码也可以$(NoWarn);
应用C#默认值。
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
要仅禁止针对特定成员的警告,请将代码括在#pragma
警告预处理器指令中。这种方法对于不应通过API文档公开的代码很有用。在以下示例中,整个Program
类将忽略警告代码CS1591
。在类定义结束时恢复警告代码的执行。用逗号分隔列表指定多个警告代码。
namespace TodoApi
{
#pragma warning disable CS1591
public class Program
{
public static void Main(string[] args) =>
BuildWebHost(args).Run();
public static IWebHost BuildWebHost(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.Build();
}
#pragma warning restore CS1591
}
将Swagger
配置为使用根据上述说明生成的XML
文件。对于Linux
或非Windows
操作系统,文件名和路径可能区分大小写。例如,一个TodoApi.XML
文件在Windows上有效,但在CentOS上无效:
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddControllers();
// Register the Swagger generator, defining 1 or more Swagger documents
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);
});
}
在前面的代码中,Reflection用于构建与Web API项目匹配的XML文件名。该AppContext.BaseDirectory属性用于构建XML文件的路径。某些Swagger
功能(例如,输入参数的模式或HTTP方法以及来自相应属性的响应代码)无需使用XML
文档文件即可工作。对于大多数功能,即方法摘要以及参数和响应代码的描述,必须使用XML文件。
向动作添加三斜杠注释可以通过将描述添加到节标题来增强Swagger UI。在操作上方添加<summary>元素Delete
:
/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
var todo = _context.TodoItems.Find(id);
if (todo == null)
{
return NotFound();
}
_context.TodoItems.Remove(todo);
_context.SaveChanges();
return NoContent();
}
Swagger UI显示前面代码<summary>元素的内部文本:
"delete": {
"tags": [
"Todo"
],
"summary": "Deletes a specific TodoItem.",
"operationId": "ApiTodoByIdDelete",
"consumes": [],
"produces": [],
"parameters": [
{
"name": "id",
"in": "path",
"description": "",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
在操作方法文档中添加一个<remarks>元素Create
。它补充了<summary>
元素中指定的信息,并提供了更强大的Swagger UI
。该<remarks>
元素的内容可以包括文本,JSON
或XML
:
/// <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);
}
请注意,UI增强还有以下附加注释:
使用在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操作:
5、描述API响应类型
使用Web API的开发人员最关心返回的内容,特别是响应类型和错误代码(如果不是标准的话)。响应类型和错误代码在XML注释和数据注释中表示。
该Create行动在成功时返回一个HTTP 201
状态码。当发布的请求正文为null
时,返回HTTP 400
状态代码。如果在Swagger
用户界面中没有适当的文档,则消费者缺乏对这些预期结果的了解。通过在以下示例中添加突出显示的行来解决该问题:
/// <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);
}
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程序包添加到项目中:
<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
如果定位.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
:
<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">
浏览至的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介绍