使用Swagger來生成asp.net core Web API 文檔

對於構建一個消費應用程序，理解API的各個方法對開發這是一個不小的挑戰。爲了使你的API更利於閱讀。
使用Swagger爲你的Web API生成好的文檔和幫助頁,.NET Core實現了Swashbuckle.AspNetCore，使用Swagger是很是簡單的，只需添加一組Nuget包和修改Startup就能夠搞定。

.Swashbuckle.AspNetCore 開源項目, ASP.NET Core Web API生成Swagger文檔的

.Swagger是一個機器可讀的restful風格的api接口的表明。他能夠支持文檔交互客戶端sdk生成，而且具備可見性

一、入門

三個主要組件：

Swashbuck.AspNetCore.Swagger：Swagger對象模型和中間件，做爲JSON終結點公開SwaggerDocument對象。

Swashbuckle.AspNetCore.SwaggerGen：一個Swagger生成器,能夠直接從路由、控制器、模型構建SwaggerDocument對象。他一般和Swagger終結點中間件結合，以自動公開SwaggerJson

Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本，Swagger UI工具的嵌入式版本，它將Swagger JSON解釋爲構建豐富的，可定製的Web API功能描述體驗。 它包括公共方法的內置測試線束。

二、經過下面命令安裝這三個組件

可使用下面方法添加Swashbuckle

Install-Package Swashbuckle.AspNetCore

三、添加並配置到Swagger到中間件

將Swagger生成器添加到Startup.cs的ConfigureServices方法中。

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();
    //註冊Swagger生成器，定義一個和多個Swagger 文檔
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });
}

Info類包含在Swashbuckle.AspNetCore.Swagger命名空間中。

在Startup.cs類的Configure方法中。啓用中間件服務，主要生成JSON文檔和SwaggerUI.

public void Configure(IApplicationBuilder app)
{
    //啓用中間件服務生成Swagger做爲JSON終結點
    app.UseSwagger();
    //啓用中間件服務對swagger-ui，指定Swagger JSON終結點
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
    app.UseMvc();
}

　　

啓動App,導航到http://localhost:<random_port>/swagger/v1/swagger.json ，顯示描述終結點的文檔。

能夠經過瀏覽http://localhost:<random_port>/swagger來查看生成的Swagger UI。

 

 

 

TodoController中的每一個公共操做方法均可以從UI進行測試。單擊一個方法名稱能夠展開節點。添加參數，單機"測試"!

四、定製和可擴展性

Swagger提供了用於記錄對象模型和自定義UI。

API Info and Description

經過將一些信息傳遞給AddSwaggerGen方法，如author、license和description

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact { Name = "Shayne Boyer", Email = "", Url = "https://twitter.com/spboyer" },
        License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
    });
});

下面圖片描述了Swagger UI顯示的版本信息

XML 註釋

啓用XML註釋

配置Swagger，讓Swagger使用生成的XML文件。對於Linux和非Window操做系統，文件名和路徑能夠區分大小寫。

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger generator, defining one or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact { Name = "Shayne Boyer", Email = "", Url = "https://twitter.com/spboyer" },
            License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
        });

        // Set the comments path for the Swagger JSON and UI.
        var basePath = PlatformServices.Default.Application.ApplicationBasePath;
        var xmlPath = Path.Combine(basePath, "TodoApi.xml"); 
        c.IncludeXmlComments(xmlPath);                
    });
}

在前面的代碼中，AppicationBasePath獲取應用程序的基本了路徑。用來查找XML註釋文件.TodoApi.xml僅適用於此示例中，引文生成的XML註釋文件的名稱基於應用程序的名稱。

像下面方法添加註釋

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.FirstOrDefault(t => t.Id == id);
    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();
    return new NoContentResult();
}

在Create方法中添加下面註釋

/// <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(typeof(TodoItem), 201)]
[ProducesResponseType(typeof(TodoItem), 400)]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

 Data Annotations

使用System.ComponentModel.DataAnnotations中的屬性裝飾模型，以幫助驅動Swagger UI組件。

將[Required]屬性添加到TodoItem類的Name屬性中：

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.

namespace TodoApi.Controllers
{
    [Produces("application/json")]
    [Route("api/[controller]")]
    public class TodoController : Controller
    {
        private readonly TodoContext _context;

隨着Web API中數據註釋的使用量的增長，UI和API幫助頁面變得更具描述性和實用性。

聲明響應類型

使用API的人員最關心的是返回什麼。特別是響應類型和錯誤代碼
當請求爲null時，Create 操做返回201建立成功和400 bad request.若是在Swagger UI中沒有合適的文檔。消費者就不瞭解這些結果。經過添加下面註釋類解決

/// <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(typeof(TodoItem), 201)]
[ProducesResponseType(typeof(TodoItem), 400)]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Swagger UI如今清楚地記錄了預期的HTTP響應代碼：