文章目錄
.Net Core中有兩個集成NSwag的包,分別爲
Swashbuckle
和NSwag
。兩者的配置大同小異。這裏以NSwag
爲例。
一、前期準備
1、初始化asp.net core 測試項目
新建asp.net core項目,此處略過;
新建apicontroller,並編寫測試代碼;
[Route("api/[controller]")]
[ApiController]
public class UserApiController : ControllerBase
{
/// <summary>
/// 獲取用戶信息,根據用戶id
/// </summary>
/// <param name="id">用戶id</param>
/// <returns></returns>
[HttpGet("getuser/{id}")]
public ActionResult GetUser(int id)
{
User u = new User { Id=1,Name="Jack"};
return Ok(new { ok = true, data = u });
}
/// <summary>
/// 添加用戶
/// </summary>
/// <param name="user">用戶信息</param>
/// <returns></returns>
[HttpPost("postuser")]
public ActionResult AddUser([FromBody]User user)
{
return Ok(new { ok = true, data = user });
}
}
public class User
{
/// <summary>
/// 用戶id
/// </summary>
public int Id { get; set; }
/// <summary>
/// 用戶姓名
/// </summary>
public string Name { get; set; }
}
2、使用nuget安裝 NSwag.AspNetCore
方式一:通過vs圖形界面安裝;
方式二:通過nuget 命令安裝:
Install-Package NSwag.AspNetCore
二、配置Swagger
1、添加並配置 Swagger 中間件
- 在應用的Startup類中的ConfigureServices 方法中,註冊所需的 Swagger 服務:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
// Register the Swagger services
services.AddSwaggerDocument()
}
- 在 Startup類中的Configure 方法中,啓用中間件爲生成的 Swagger 規範和 Swagger UI 提供服務:
public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles();
// Register the Swagger generator and the Swagger UI middlewares
app.UseOpenApi();
app.UseSwaggerUi3();
app.UseMvc();
}
- 啓動應用。 轉到:
http://localhost:/swagger,以查看 Swagger UI。
http://localhost:/swagger/v1/swagger.json,以查看 Swagger 規範。
2、自定義 API 文檔
API 信息和說明
在 Startup.ConfigureServices 方法中,傳遞給 AddSwaggerDocument 方法的配置操作會添加諸如作者、許可證和說明的信息:
public void ConfigureServices(IServiceCollection services)
{
//services.AddControllers();
services.AddControllersWithViews();
services.AddSwaggerDocument(config =>
{
config.PostProcess = document =>
{
document.Info.Version = "v1";
document.Info.Title = "UserManageApp API";
document.Info.Description = "A simple ASP.NET Core web API";
document.Info.TermsOfService = "None";
document.Info.Contact = new NSwag.OpenApiContact
{
Name = "張三",
Email = string.Empty,
Url = "https://example.com"
};
document.Info.License = new NSwag.OpenApiLicense
{
Name = "Use under LICX",
Url = "https://example.com/license"
};
};
});
}
Swagger UI 顯示版本的信息:
XML 註釋
若要啓用 XML 註釋,請執行以下步驟:
以windows先使用vs爲例:
- 在“解決方案資源管理器”中右鍵單擊該項目,然後選擇“編輯 <project_name>.csproj” 。
- 手動將突出顯示的行添加到 .csproj 文件 :
三、參考
*以上講解知識入門級的,能大體使用起來,能滿足一般性需求;