第十二节: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 : 原创博客请在转载时保留原文链接或在文章开头加上本人博客地址,否则保留追究法律责任的权利。
 
posted @ 2019-03-19 10:37 Yaopengfei 阅读(...) 评论(...) 编辑 收藏