第十二节：WebApi自动生成在线Api文档的两种方式

一. WebApi自带生成api文档

1. 说明

　　通过观察，发现WebApi项目中Area文件夹下有一个HelpPage文件夹，如下图，该文件夹就是WebApi自带的生成Api的方式，如果该文件夹没了，可以通过Nuget安装：Microsoft.AspNet.WebApi.HelpPage ，你就会发现下图这一坨代码又回来了。

　　

 

使用：http://localhost:2131/Help/Index , 即可访问生成的Api目录，如下图：

缺点：你会发现一个很坑爹的问题，方法名的注释和参数的注释均不显示，这对使用者而言，相当不放方便了。

2. 改进支持参数的注释

 (1). 选中项目，右键属性，填写生成xml文件的路径，如下图： bin\api.xml

(2). 找到 Areas/HelpPage/App_Start  目录下的HelpPageConfig.cs 文件，Register 方法，添加一行代码：

   config.SetDocumentationProvider(new XmlDocumentationProvider(AppDomain.CurrentDomain.BaseDirectory + "bin\\api.xml"));

(3). 大功告成，再次访问 http://localhost:2131/Help/Index ，发现无论是方法名还是参数名，均有描述了

 

 

 3. 小结

　　上述通过改进，已经生成比较完善的Api文档了，但美中不足的是不能直接测试，当然可以整合别的控件使其支持，但比较麻烦，不如使用下面的SwashBuckle生成SwaggerUI形式的Api文档。  

 

二. 借助SwaggerUI生成api文档

 1. 通过Nuget安装 Swashbuckle （版本：5.6.0）程序集，会发现在 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置  SwaggerUI 相关展示行为的，如下图：

 

 (2). 选中项目，右键属性，勾上xml文档文件，注意：这里默认是什么就保留什么，不要在自己改了 。如下图： bin\05-WebApiExtend.xml

 

 

(3). 在SwaggerConfig.cs文件中 搜索 【  c.IncludeXmlComments(GetXmlCommentsPath());  】，在这句话的下面新增一句代码：

  c.IncludeXmlComments(AppDomain.CurrentDomain.BaseDirectory + "bin\\05-WebApiExtend.xml");

(4). 大功告成，访问：http://localhost:2182/swagger/ui/index  ，即可查看生成Api文档。

 

 

 

 

 

 

 

!

• 作       者 : Yaopengfei(姚鹏飞)
• 博客地址 : http://www.cnblogs.com/yaopengfei/
• 声     明1 : 本人才疏学浅，用郭德纲的话说“我是一个小学生”，如有错误，欢迎讨论，请勿谩骂^_^。
• 声     明2 : 原创博客请在转载时保留原文链接或在文章开头加上本人博客地址，否则保留追究法律责任的权利。