Web Api 2.0中使用Swagger生成Api文檔的2個小Tips

當Web Api 2.0使用OAuth2授權時，如何在Swagger中添加Authorization請求頭？

Swagger說明文檔支持手動調用Api, 但是當Api使用OAuth2授權時，由於沒有地方可以輸入授權Token, 導致響應結果一直是401沒有授權。

解決方案：

在Swagger配置文件中，添加對請求頭中Authorization的設置。

1. 在Api項目中添加一個新類AddAuthorizationHeader並實現IOperationFilter介面

    public class AddAuthorizationHeader : IOperationFilter
    {
        /// <summary>
        /// Adds an authorization header to the given operation in Swagger.
        /// </summary>
        /// <param name="operation">The Swashbuckle operation.</param>
        /// <param name="schemaRegistry">The Swashbuckle schema registry.</param>
        /// <param name="apiDescription">The Swashbuckle api description.</param>
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            if (operation == null) return;

            if (operation.parameters == null)
            {
                operation.parameters = new List<Parameter>();

            }


            var parameter = new Parameter
            {
                description = "Token",
                @in = "header",
                name = "Authorization",
                required = true,
                type = "string"
            };


            if (apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any())
            {
                //如果Api方法是允許匿名方法，Token不是必填的

                parameter.required = false;
            }

            operation.parameters.Add(parameter);
        }
    }

2. 在SwaggerConfig.cs中啟用Authorization請求頭。

        public static void Register(HttpConfiguration config)
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            config.EnableSwagger(c =>
            {

                c.OperationFilter<AddAuthorizationHeader>();

                c.SingleApiVersion("v1", "EHealthCareClinic.WebApi");

                c.IncludeXmlComments(GetXmlCommentsPath());
            })
            .EnableSwaggerUi(c =>
            {
            });
        }

3. 編譯Api項目，重新打開Swagger說明文檔， Parameters列表中就會出現Authorization變數，錄入正確的授權Token,  401未授權問題消失。

當Web Api 2.0使用IHttpActionResult作為返回值時，如何在Swagger中生成Response Class範例？

IHttpActionResult是Web Api 2.0引入的介面。

使用IHttpActionResult作為Api  返回值的好處。

• 簡化對控制器的單元測試
• 創建Http響應的通用邏輯被移動到單獨的類中
• 通過隱藏構建相應的底層細節，使控制器動作更清晰

Swagger生成文檔的原理是通過讀取Web Api項目生成的XML文檔說明文件，使用反射技術，動態展示每個Action方法的方法簽名。

但是當使用IHttpActionResult作為Api方法返回值之後，Swagger不能通過反射正確讀取到返回值的類型，所以導致生成的文檔缺少。

例：

        /// <summary>
        /// 獲取省份列表
        /// <param name="countryId">國家ID</param>
        /// </summary>
        [HttpGet]
        [Route("countries/{countryId}/provinces")]
        public IHttpActionResult GetProvinceList(Guid countryId)
        {
            var result = QueryService.GetProvinceCollection(new CountryId(countryId));
            return Ok(result);
        }

解決方案:

Web Api 2.0中引入了一個新的特性類System.Web.Http.Description.ResponseTypeAttribute。

這個特性類構造只有一個參數，即返回值的類型。

我們只需要在每個Api方法簽名處使用這個新特性聲明Api返回值的類型, Swagger生成的說明文檔中就會出現返回類型的說明。

        /// <summary>
        /// 獲取省份列表
        /// <param name="countryId">國家ID</param>
        /// </summary>
        [HttpGet]
        [Route("countries/{countryId}/provinces")]
        [ResponseType(typeof(IEnumerable<EHealthCareClinic.Business.QueryModel.ProvincePresentation>))]
        public IHttpActionResult GetProvinceList(Guid countryId)
        {
            var result = QueryService.GetProvinceCollection(new CountryId(countryId));
            return Ok(result);
        }