在开发Web API时，为API编写文档是一个重要的步骤，它可以帮助开发者和最终用户更好地理解和使用API。Swagger是一个广泛使用的API文档生成工具，而Swashbuckle.AspNetCore是为ASP.NET Core设计的Swagger集成库。本文将介绍如何在ASP.NET CoreWeb API项目中使用Swagger和Swashbuckle生成API文档。
要开始使用Swagger和Swashbuckle，首先需要在项目中添加NuGet包Swashbuckle.AspNetCore。然后，需要在项目的Startup类中配置服务和中间件以支持Swagger。以下是配置的示例代码：
public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(options =>
{
options.SwaggerDoc(
"help",
new Info
{
Title = "Fiver.Api Help",
Version = "v1"
});
});
// 其他服务配置
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint(
"/swagger/help/swagger.json",
"Fiver.Api Help Endpoint"
);
});
// 其他中间件配置
}
通过以上配置，Swagger文档页面可以通过以下URL访问：
[host]/swagger
Swagger是一种用于描述RESTful API的格式，Swashbuckle可以生成这些Swagger文档。需要注意的是，配置服务时通过SwaggerDoc方法指定的名称（例如示例代码中的“help”）必须与SwaggerEndpoint方法中指定的名称相同。
Swagger生成的文档可以包含XML文档。这可以通过项目的属性 > 构建标签配置来启用，并配置Swagger服务。以下是配置的示例代码：
var xmlDocPath = PlatformServices.Default.Application.ApplicationBasePath;
options.IncludeXmlComments(Path.Combine(xmlDocPath, "Fiver.Api.Help.xml"));
使用XML注释，可以在模型和动作属性上使用数据注释，以生成详细的文档，这对客户端开发者非常有用。例如：
///
<summary>
///
Adds a new movie
///
</summary>
///
<remarks>
///
A sample request body
///
///
POST /movies
///
{
///
"title": "Thunderball",
///
"releaseYear": 1965,
///
"summary": "James Bond heads to The Bahamas to recover two nuclear
///
warheads stolen by SPECTRE"
///
}
///
</remarks>
///
<returns>
Newly added movie
</returns>
///
<response code="201">
if movie created
</response>
///
<response code="400">
if input null or invalid
</response>
[HttpPost]
[ProducesResponseType(typeof(MovieOutputModel), 201)]
[Produces("application/json", Type = typeof(MovieOutputModel))]