Part 2: Sử dụng Token với Swagger UI (SwashBuckler)

ASP.NET Web API Help Page

Khi tạo project Web API, sẽ có 1 nuget tên là Microsoft ASP.NET Web Api Help Page được cài đặt để tạo trang Help cho Web API.


Khi click vào một API nào đó, sẽ hiện ra trang detail của API đó

Tuy nhiên vấn đề đặt ra là bạn không thể test API đó. Để test API, bạn có thể dùng PostMan, Fiddle, …Nhưng phải nhập domain, header, model…
Rất may mắn, có 1 công cụ hỗ trợ cho bạn test thật dễ dàng. Đó là Swagger.

Thêm Swagger vào Web Api Project

Để thêm Swagger vào ASP.NET Web API, bạn cần cài đặt Swashbuckle thông qua nuget.

Install-Package Swashbuckle

Sau khi cài đặt, sẽ có 1 file mới tên là SwaggerConfig.cs được thêm vào App_Start.

Thiết lập Swagger

Để thay đổi title, bạn cập nhật:

c.SingleApiVersion("v1", "Athentication and Authorization");

Mở browser, trỏ trình duyệt tới địa chỉ http://localhost:[PORT_NUM]/swagger. Bạn sẽ thấy trang Swagger UI help.

Tuy nhiên các api đều không có comment. Để thêm comment, bạn cần sử dụng XML comments

Trong file SwaggerConfig.cs, uncomment đoạn:

c.IncludeXmlComments(GetXmlCommentsPath());

Bạn bổ sung hàm GetXmlCommentsPath:

private static string GetXmlCommentsPath()
{
 return string.Format(@"{0}\SwaggerXml\Api.XML", AppDomain.CurrentDomain.BaseDirectory);
}

Sau đó, bạn cần comment cho API và model

Refresh lại trang Swagger, bạn sẽ thấy những comment đó sẽ được hiển thị trong API.

Trường hợp bạn muốn trả về Http Status Code và kiểu dữ liệu trả về, bạn sử dụng SwaggerResponse

/// <summary>
/// Get by id
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[SwaggerResponse(200, "Returns the id of list object", typeof(string))]
[SwaggerResponse(400, "Not Found")]
[SwaggerResponse(500, "Server error")]
public string Get(int id)
{
 return "value";
}

Định nghĩa Enum

Giả sử bạn có định nghĩa:

/// <summary>
/// Person
/// </summary>
public class Person
{
 /// <summary>
 /// First Name
 /// </summary>
 public string FirstName { get; set; }
 /// <summary>
 /// Last Name
 /// </summary>
 public string LastName { get; set; }
 /// <summary>
 /// Primary language
 /// </summary>
 public Language PrimaryLanguage { get; set; }
}
/// <summary>
/// Language
/// </summary>
public enum Language
{
 /// <summary>
 /// English
 /// </summary>
 English,      
 /// <summary>
 /// Mandarin
 /// </summary>
 Mandarin,
 /// <summary>
 /// Cantonese
 /// </summary>
 Cantonese,
 /// <summary>
 /// Vietnamese
 /// </summary>
 Vietnamese
}

Và bạn có thêm 1 API getPerson

/// <summary>
/// Get Person
/// </summary>
/// <returns></returns>
[Route("Person")]
[HttpGet]
public Person Get()
{
 var person = new Person()
 {
  FirstName = "MingXin",
  LastName = "Zhao",
  PrimaryLanguage = Language.English
 };
 return person;
}

Bạn sẽ thấy số 0,1,2,3 thay vì English, Mandarin, Cantonese hoặc Vietnamese

Để giải quyết trường hợp này, bạn mở file SwaggerConfig.cs, mở đoạn comment

c.DescribeAllEnumsAsStrings();

Sau đó F5 để refresh lại trình duyệt, bạn sẽ thấy kết quả như bên dưới.
Như vậy, sau bài viết này, bạn sẽ nắm được cách sử dụng Swagger trong project Web API. Trong bài viết tới, mình sẽ hướng dẫn sử dụng Token trên trang Swagger index.

Chúc các bạn thành công

Updated:

Part 2: Sử dụng Token với Swagger UI (SwashBuckler)