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

Trong bài viết này, mình sẽ hướng dẫn các bạn thêm hàm đăng nhập (operation) /token và cách đính kèm token trong mỗi request từ Swagger.
Nếu bạn chưa biết cách sử dụng Swagger, bạn tham khảo thêm bài viết: Thêm Swagger vào Web API

Thêm 1 operation token vào document

Mặc định hàm đăng nhập để lấy token sẽ không được hiển thị trong Swagger. Nếu muốn hiển thị hàm đăng nhập, bạn phải tùy chỉnh IDocumentFilter.
Interface IDocumentFilter được định nghĩa như sau:

public interface IDocumentFilter
{
 void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer);
}

Đầu tiên, bạn thêm TokenOperation vào file SwaggerConfig.cs

c.DocumentFilter<TokenOperation>();

Tạo file TokenOperation:

public class TokenOperation : IDocumentFilter
{
 /// <summary>
 /// Add authentication operation
 /// </summary>
 /// <param name="swaggerDoc"></param>
 /// <param name="schemaRegistry"></param>
 /// <param name="apiExplorer"></param>
 public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
 {
  swaggerDoc.paths.Add("/token", new PathItem
  {
   post = new Operation
   {
    operationId = "CreateToken",
    summary = "Login",                    
    tags = new List<string> { "Account" },
    consumes = new List<string> { "application/x-www-form-urlencoded" },
    responses = new Dictionary<string, Response>
    {
     { "400",new Response()
      {
       description = "Bad Request"
      }
     },
     { "401",new Response()
      {
       description = "Invalid credential"
      }
     },
     { "500",new Response()
      {
       description = "Internal Server Error"
      }
     },
     { "200",new Response
      {
       description = "Success, return information of user session",
       //schema = schemaRegistry.GetOrRegister(typeof(LoginResult)),                                
       schema = new Schema()
       {
        example = new LoginResult
          {
           access_token = "FrUDm7H57_CtfNg5A0NmIZyRQTeJHGLScBIGvjdbOFny1k875RAL4XTkSbcrYvI4YgqM4zmoV68MKMKeXsxARkKHgI8E3v4R5YmarYceHDKoBIul099nK-xVw5-GksgpUhUA2FzXFQIH-wTBygRSi3FsVj2nrX4blQBGknihdOrLe4DDiPsStHh8VX8kAUwAuz4u0Iklsj0Th7HaKmj-SWEm1AVVOvvgHlSGrs8JwMnDGdN051yUYq8wuXV6fJJRTyu2HDg6ZHzribMwj6_KZlEmgnJZqtkwzTpzvaLuipKquxrFIzmbPEI9i7Xy6PhKVPb7pzaISFCkD6K95oYlce2S5FvWDk-bJ-ZLrfDVvEzeIuxlN0MPT2rWGPADtDxh2BO0aByY5K1u8nC3bP8eha1ko7W0A5DmnHcGRYzby1bsWVdiP5FAbvAXCPHY__WxonAIV7OTEkEMmIZJGmpztKMEuO0gN53OdVFqzMH9uqaLziy1nmxxX-JQd3-PTYt9",
           expires_in = 31535999,
           token_type = "bearer",
           username="yourname@your-website-domain.com",
           issued = "Wed, 12 Jul 2017 06:48:13 GMT",
           expires = "Wed, 19 Jul 2017 06:48:13 GMT"
          },
        type = "object",
        title = "LoginResult",
        properties = new Dictionary<string, Schema>
        {
         { "access_token", schemaRegistry.GetOrRegister(typeof(string)) },
         { "expires_in", schemaRegistry.GetOrRegister(typeof(int)) },
         { "token_type", schemaRegistry.GetOrRegister(typeof(string)) },
         { "username", schemaRegistry.GetOrRegister(typeof(string)) },
         { "issued", schemaRegistry.GetOrRegister(typeof(string)) },
         { "expires", schemaRegistry.GetOrRegister(typeof(string)) }
        }
       }
      }
     }
    },
    //grant_type=password&username=username& password=password
    parameters = new List<Parameter>
    {
     new Parameter
     {
      name = "grant_type",
      type = "string",
      description = "must be 'password'",
      @default = "password",
      @in = "formData",
      required = true
     },
     new Parameter
     {
      name = "username",
      type = "string",
      description = "username",                            
      @in = "formData",
      required = true
     },
     new Parameter
     {
      name = "password",
      type = "string",
      description = "password",                            
      @in = "formData",
      required = true
     }
    },
    description = "Login to get access token"
   }
  });            
 }
}

Để biết hàm token cần tham số gì, bạn dùng fiddle để tạo request. Mặc định khi dùng Web API, api Token cần phương thức:

Method: POST
Content-type: "application/x-www-form-urlencoded"
Body: grant_type=password&username=username& password=password

Khai báo hàm token trong group Account:

tags = new List { "Account" }

Ngoài ra mình tạo thêm class LoginResult để đưa ra example trong document

/// <summary>
/// Login result
/// </summary>
public class LoginResult
{
 /// <summary>
 /// access token
 /// </summary>
 public string access_token { get; set; }
 /// <summary>
 /// expires in
 /// </summary>
 public int expires_in { get; set; }
 /// <summary>
 /// token type
 /// </summary>
 public string token_type { get; set; }
 /// <summary>
 /// User Name
 /// </summary>
 public string username { get; set; }
 /// <summary>
 /// .issued=Wed, 12 Jul 2017 06:48:13 GMT
 /// </summary>
 public string issued { get; set; }
 /// <summary>
 /// Expires
 /// </summary>        
 public string expires { get; set; }
}

Kết quả cuối cùng:

Đăng nhập bằng Token trong Swashbuckle

Ý tưởng là mỗi lần request, chúng ta sẽ nhét vào header đoạn: Authorization: Bearer <your token>
Trong file swaggerConfig.cs, thêm dòng code:

c.InjectJavaScript(typeof(SwaggerConfig).Assembly, "[your project name].SwaggerXml.customSwaggerHeader.js");

Bạn thêm file customSwaggerHeader vào folder SwaggerXml:

$(function () {
    $('#input_apiKey').attr("placeholder", "bearer token");
    $('#input_apiKey').off();
    $('#input_apiKey').change(function () {
        var token = this.value;
        if (token && token.trim() !== '') {
            token = 'Bearer ' + token;
            var apiKeyAuth = new window.SwaggerClient.ApiKeyAuthorization("Authorization", token, "header");
            window.swaggerUi.api.clientAuthorizations.add("token", apiKeyAuth);
        }
    });
})();

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