[Asp .Net MVC][WebAPI] Swashbuckle – Swagger Framework for API

利用Swashbuckle来制作Web API文档,开发WebAPI后:
(O)就可以让介接工程师参考与进行测试。
(X)就是叫其他工程师没事别烦我的工具。


前言:

回想约三年前的第一份工作,在 Java Application 或 Android App 项目开发过程中,与其他开
发者沟通与确认WebAPI格式是必须且非常繁琐的。虽然工作内容不难,但常常因为一些细节
耗费相当多的时间。
在开发过程中,必须要了解WebAPI使用方式、解析或回传不同格式数据(XML、JSON)、需
要保持数据一致性...等。所以我们必须以文档纪录这些资讯,并作为开发者之间沟通的方式。

早期纪录的方式,以简单的Google document或Word方式纪录与说明 WebAPI,记录范例如
下:

方法:GET
参数格式:String
参数名称:Id
回传数据格式:JSON
回传数据内容:{ "name" : "duran" }

这种纪录方式有些缺点:
1.人工撰写文档:非常花费时间。
2.文字记录错误:因为人工输入,运气不好可能因为错字花费很多时间。
3.无法即时测试:Get可能方便测试,输入网址即可测试,如果是Post呢? 如果有10个参数呢?
                             如果超长JSON呢?
4.难以纪录历程:问题比较小,使用版本控管软件可以解决这个问题。
5.文档不够详细:可能又要找WebAPI开发者讨论,花费时间。


换了新环境,当然也要入境随俗的偷学新东西!! 而不能像过去一样花费时间在锁碎的
问题上!!
今天这篇主要简单介绍swashbuckle,一个整合ApiExplorer and Swagger/swagger-ui,容易安装、
容易维护WebAPI与可以进行测试的好用套件。

这篇文章将同时发布在点部落与个人blogger



Install Package:


Step.1 开启Visual Studio,点选New Project...
         Open Visual Studio,  Click New Project...




Step.2 选择"ASP .NET 4 Web Application", 输入项目名称"SwaggerDemo"
         Select "ASP .NET 4 Web Application", Enter "SwaggerDemo" in Project Name textbox



Step.3 选择Web API
         Select Web API



Step.4 选择 TOOLS >> NuGet Package Manager >> Manage NuGet Packages for Solution...
         Select TOOLS >> NuGet Package Manager >> Manage NuGet Packages for Solution...



Step.5 输入swashbuckle进行搜寻,点选Install安装"swashbuckle - Swagger for WebApi"
         Enter "swashbuckle" in search box, and click Install button to install
         "swashbuckle - Swagger for WebApi"



Step.6 启动项目,浏览器上输入网址"http://localhost:xxxxx/swagger/" (xxxxx是port)
         Start Project, and enter url "http://localhost:xxxxx/swagger/" on browser (xxxxx is port)




Step 7.你会看到Values WebAPI所有的服务,如下图:
          You can see all web service of  "Values WebAPI":






Step.8 展开"/api/Values",点选"Try it out" , 你将会看到测试结果
         Expand  "/api/Values", click "Try it out", you will see the result


Step.8 展开"/api/Values/{Id}",输入数据并点选"Try it out" , 你将会看到测试结果
         Expand  "/api/Values", Enter parameters and click "Try it out", you will see the result





SwaggerReponse:


您可以加入SwaggerReponse Annotations 表示响应呈现消息(Reponse Message)
You can add SwaggerReponse Annotations for Reponse Message

[SwaggerResponse(HttpStatusCode.OK, @"retrun vaule", typeof(bool))]
[SwaggerResponse(HttpStatusCode.InternalServerError, @"Server error", typeof(bool))]
[SwaggerResponse(HttpStatusCode.MethodNotAllowed, @"Invalid input", typeof(bool))]







XmlComments:


您可以借由xml comments来让API 文档更详细。
You can make the API doucment completely by xml comments

Step.1 右键点选solution >> properties
          Right click solution >> properties



Step.2 在"Build"页面,勾选"XML doucmentation"并输入路径"App_DataSwaggerDemo.XML"
          In Build tab, Check "XML doucmentation" and enter "App_DataSwaggerDemo.XML" in 
          path textbox





Step.3 开启App_StartSwaggerConfig.cs,输入下列命令
         Open App_StartSwaggerConfig.cs,add the code as shown

c.IncludeXmlComments(string.Format(@"{0}App_DataSwaggerDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory));



Step.4 加入xml comments
         Add xml comments




Step.5 执行项目
         Start Project





范例程序下载:


https://dl.dropboxusercontent.com/u/13585157/SwaggerDemo.zip


参考数据:


http://swagger.io/
http://www.wmpratt.com/swagger-and-asp-net-web-api-part-1/