通過Swashbukle給DotNet Core Web API 增加自動文檔功能
DotNet Core Web API給開發者提供了一個很好的框架來開發Restful的API。那麽這些API接口該如何管理起來呢?Swagger是一個很好的選擇,Swagger不需要開發者額外去維護接口文檔,只要開發者的接口遵循Restful的規範,Swagger就會根據API接口生成文檔。
對於前後端分離的開發模式,前後端開發者一般會先定義好接口,然後各自獨立開發,後端開發者可以使用Swagger很快的生成沒有業務邏輯的接口文檔,接口返回的是Mock Data,這樣前端開發人員就可以更早的開始調用接口,只要關註Swagger的接口文檔是否有發生變化,盡早的發現錯誤,避免了前後端最後集成時,出現大問題。
後端開發者使用Swagger也可以很好的調試,Swagger提供了一個簡單的UI界面,可以模擬簡單的post,get,put 。功能沒有curl或者postman強大,但是優勢在於簡單快捷,只要在swagger文檔界面點點就可以。
這裏要介紹的就是:Dotnet Core 2.0 下面的 Swashbukle.AspNetCore
Github地址: https://github.com/domaindrivendev/Swashbuckle.AspNetCore
這篇文章的源碼:dotnet-core-sample 的 sample1中
1.首先創建一個dotnet core web api 項目,通過命令行輸入
dotnet new webapi -name sample1
2. 然後下載Swashbuckle AspNetCore
dotnet add package Swashbuckle.AspNetCore
在VS 2017下面,通過 工具 -> Nuget 包管理器 -> 程序包管理控制臺, 運行
Install-Package Swashbuckle.AspNetCore
註意:這裏運行的是Install-Package Swashbuckle.AspNetCore 不是Install-Package Swashbuckle
3.在Startup.cs文件中,引入Swashbuckle
using Swashbuckle.AspNetCore.Swagger;
4.在Startup.cs文件中的ConfigureService方法中註冊Swagger Generator
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(config =>
{
config.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
5. 在Configure方法中添加Swagger的中間件
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseMvc();
app.UseSwagger();
}
6. 最後執行一下dotnet run或者F5,就可以直接運行項目了
dotnet run
默認情況下,可以通過http://localhost:5000/swagger/ 訪問API接口文檔
註意:要自動生成文檔,對應Controller下的接口必須顯示的指定用那種Http請求方式,POST,GET,PUT,DELETE
Swagger運行起來後,有時候需要針對項目進行一些簡單的配置:
除了前面提到的 new Info { Title = "My API", Version = "v1" },Swashbukle還可以配置其他信息,具體可以參見OpenAPI Specification.
config.SwaggerDoc("v1",
new Info
{
Title = "My API - V1",
Version = "v1",
Description = "A sample API to demo Swashbuckle",
TermsOfService = "Knock yourself out",
Contact = new Contact
{
Name = "Joe Developer",
Email = "[email protected]"
},
License = new License
{
Name = "Apache 2.0",
Url = "http://www.apache.org/licenses/LICENSE-2.0.html"
}
}
)
最後,如果要配置多個swagger文檔,需要通知添加swagger generator和endpoint
config.SwaggerDoc("v2", new Info { Title = "My API - V2", Version = "v2" });
config.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
通過Swashbukle給DotNet Core Web API 增加自動文檔功能