zoukankan      html  css  js  c++  java
  • 第十二节:WebApi自动生成在线Api文档的两种方式

    一. WebApi自带生成api文档

    1. 说明

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

      

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

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

    2. 改进支持参数的注释

     (1). 选中项目,右键属性,填写生成xml文件的路径,如下图: binapi.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文档文件,注意:这里默认是什么就保留什么,不要在自己改了 。如下图: bin5-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 : 原创博客请在转载时保留原文链接或在文章开头加上本人博客地址,否则保留追究法律责任的权利。
     
  • 相关阅读:
    C++中字符数组和字符指针问题
    C++中的常量指针和指针常量
    C++中指针形参问题
    Xcode视图调试Debug View Hierarchy
    第3章 程序的机器级表示(深入理解计算机系统)
    第2章 信息的表示和处理(深入理解计算机系统)
    第1章 计算机系统漫游(深入理解计算机系统)
    用gcc编译.cpp文件可能出现"undefined reference to `__gxx_personality_v0'"问题的解决
    第12章 并发编程(深入理解计算机系统)
    第11章 网络编程(深入理解计算机系统)
  • 原文地址:https://www.cnblogs.com/yaopengfei/p/10557024.html
Copyright © 2011-2022 走看看