[Tools] 使用 Swashbuckle 自动建立 Web API 线上说明文档

使用 Swashbuckle - Swagger for WebApi 自动建立 Web API 线上说明文档


前言

开发Web API服务给其他系统串接使用时,由于初期的异动性较高,因此常常会有调整个需求,如果还是以传统的方式使用规格文档(Excel/Word)作为沟通方式,其实时效性是相当差的,而且有可能会发生规格文档与实际程序不符的情况发生。此时就可以使用 Swashbuckle 作为线上API说明文档的产生器,让文档透过程序注解自动产出,达到文档规格与程序需求完全一致,避免上述问题及困扰发生。以下介绍。

环境

  • Visual Studio 2015
  • Swashbuckle v5.3.2

环境建立

简单建立一个WebAPI项目,以及相关分层类库项目。

在WebAPI项目中使用Nuget下载安装Swashbuckle套件,会连同Swashbuckle.Core一并下载。

资讯来源

线上说明文档的资讯来源可想而知一定是从注解来的,因此我们需要将XML文档文件输出。由于WebAPI项目(SwaggerSample.WebAPI)中会参考使用到其他项目(SwaggerSample.Service)类,因此也要一并输出才会在线上说明文档中显示。直接右键点选项目选择属性,切换至建置页签后在输出设定中勾选XML文档文件即可。

SwaggerSample.WebAPI

SwaggerSample.Service

在来由于布署网站的便利性,透过建置后事件命令集将所有XML文件集中至App_Data数据夹中。

xcopy /y "$(TargetDir)SwaggerSample.Webapi.xml" "$(ProjectDir)App_Data"
xcopy /y "$(TargetDir)SwaggerSample.Service.xml" "$(ProjectDir)App_Data"

建置后确实将XML都复制到App_Data数据夹中

最后只要告诉 Swagger 所需XML文件放置位置就可以了

先打开 App_Start  SwaggerConfig 配置文件

加上2个取得XML文件路径的方法

private static string GetXmlCommentsPath()
{
    return string.Format(@"{0}App_DataSwaggerSample.Webapi.XML",
        System.AppDomain.CurrentDomain.BaseDirectory);
}

private static string GetXmlServiceCommentsPath()
{
    return string.Format(@"{0}App_DataSwaggerSample.Service.xml",
        System.AppDomain.CurrentDomain.BaseDirectory);
}

最后在Register方法中设定XML文件路径(可允许多笔),一切就大功告成啦!!

c.IncludeXmlComments(GetXmlCommentsPath());
c.IncludeXmlComments(GetXmlServiceCommentsPath());

火力展示

启动站台后,直接在WebAPI路径后方加上swagger就可以进入线上说明文档页面

http://localhost:32963/swagger/

可以清楚了解此站台提供多少种API服务

以登入功能为例,点选后展开文档如下,文档上的数据都是对应到程序注解中。

对应代码如下,稍微比较一下就可以知道注解相对于文档上的位置了

/// 
/// 登入
/// 
/// 账号
/// 密码
/// 
/// 执行登入作业
/// 
/// 作业完成,返回结果数据
/// 作业发生错误
[ResponseType(typeof(LoginResult))]
public IHttpActionResult Login(string account, string password)
{
    try
    {
        var loginResult = new LoginResult();

        if (account == "1" && password == "2")
        {
            loginResult.IsSuccess = true;
            loginResult.ResultCode = "100";
            loginResult.ResultMessage = "登入成功";
        }
        else
        {
            loginResult.IsSuccess = false;
            loginResult.ResultCode = "200";
            loginResult.ResultMessage = "账号密码错误";
        }

        return Ok(loginResult);
    }
    catch (Exception)
    {
        // log exception here
        return BadRequest("异常");
    }
}

登入回传结果之类如下

namespace SwaggerSample.Service.DTO
{
    public class LoginResult
    {
        /// 
        /// 作业是否成功
        /// 
        public bool IsSuccess { get; set; }

        /// 
        /// 结果代码
        /// 
        public string ResultCode { get; set; }

        /// 
        /// 结果描述
        /// 
        public string ResultMessage { get; set; }
    }
}

另外还可以直接在页面上直接点选Try it out测试API功能,真是方便阿

参考资讯

http://kevintsengtw.blogspot.tw/2015/12/swashbuckle-swagger-for-web-api.html

http://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-U


希望此篇文章可以帮助到需要的人

若内容有误或有其他建议请不吝留言给笔者喔 !