Asp.Net Core 轻松学-利用 Swagger 自动生成接口文档

前言

    目前市场上主流的开发模式，几乎清一色的前后端分离方式，作为服务端开发人员，我们有义务提供给各个客户端良好的开发文档，以方便对接，减少沟通时间，提高开发效率；对于开发人员来说，编写接口文档需要消耗大量的时间，并且，手动编写的文档接口会由于需求的频繁变动变得难以维护，这就需要一个在接口开发阶段可以自动监测接口输入参数，自动生成文档的功能；由于 swagger 插件的出现，这项工作几乎可以实现完全的自动化。

1. 什么是 swagger

    swagger 是由 smartbear 公司开发的一款 api 文档自动化工具，其采用 apache 2.0 免费开源授权协议，允许任何人免费使用该工具，利用 swagger 的特性，可以很方便在没有任何实现逻辑的情况下生成可视化和与api资源交互界面，swagger 支持 api 分类导航，提供 api 测试套件，完全的可定制化，对开发人员和 api 消费者都非常友好。

2. 开始使用 swagger

• 2.1 首先建立一个 asp.net core api 项目，并从 nuget 上引用 swagger 包

• 2.2 右键点击项目“依赖项”，选择 “管理 nuget 程序包(n)”，这浏览标签页输入包名进行安装，选择稳定版即可，此处我选择的版本是 4.0.1

swashbuckle.aspnetcore
swashbuckle.aspnetcore.annotations

• 2.3 首先我们要对项目进行设置，确保生成项目的 xml 文档，如下图
  右键点击项目-属性-生成，勾选 "xml 文档文件"

• 2.4 接下来需要在 startup.cs 中将 swagger 加入管道中

        static string[] docs = new[] { "未分类" };

        public void configureservices(iservicecollection services)
        {
            services.addmvc().setcompatibilityversion(compatibilityversion.version_2_1);

            if (env.isdevelopment())
            {
                services.addswaggergen(options =>
               {
                   foreach (var doc in docs) options.swaggerdoc(doc, new info { version = doc });
                   options.docinclusionpredicate((docname, description) =>
                   {
                       description.trygetmethodinfo(out methodinfo mi);

                       var attr = mi.declaringtype.getcustomattribute<apiexplorersettingsattribute>();
                       if (attr != null)
                       {
                           return attr.groupname == docname;
                       }
                       else
                       {
                           return docname == "未分类";
                       }
                   });
                   options.customschemaids(d => d.fullname);
                   options.includexmlcomments("ron.swaggertest.xml", true);
               });
            }
        }

        // this method gets called by the runtime. use this method to configure the http request pipeline.
        public void configure(iapplicationbuilder app, ihostingenvironment env)
        {
            if (env.isdevelopment())
            {
                app.usedeveloperexceptionpage();
                app.useswagger()
                   .useswaggerui(options =>
                {
                    options.documenttitle = "ron.liang swagger 测试文档";
                    foreach (var item in docs)
                        options.swaggerendpoint($"/swagger/{item}/swagger.json", item);
                });
            }

            app.usemvc();
        }
    }

• 2.5 以上代码首先定义了一个常量，表示文档分类列表，默认值给了一个 “未分类”，然后在 configureservices 和 configure 方法中判断是开发环境才会引用 swagger 进行 api 文档的生成，之所以要增加一个 “未分类”，是因为在我们没有对 api 进行分组的时候，默认把未分组的 api 归并到此分类下，好了，现在运行项目

• 2.6 这浏览器中输入地址

http://localhost:5000/swagger/index.html

• 看到 api 文档已经成功生成

• 可以看到，各种不同的 httpmethod 都有不同的颜色进行区分显示，点击该 api ，可以看到详细的输入参数，点击 api 接口右边的 try it out ，还可以对接口进行实时测试，是不是觉得有一中连单元测试都免了的感觉。

• 在上图中，红圈部分是我们编写的 xml 注释，可以看到，都被完整的抓取并显示出来了

3. 定义 api 分组

• 上面是默认的 api 文档，在实际开发中，肯定需要对 api 进行分组和完善输出参数给消费者，现在就来对 controller 进行改进，首先是设置分组名称

• 3.1 定义分组

    [route("api/[controller]"), apiexplorersettings(groupname = "演示分组")]
    [apicontroller]
    public class valuescontroller : controllerbase

• 上面的代码在 valuescontroller 上增加了一个特性 apiexplorersettings(groupname = "演示分组"),这样就完成了一个分组设置；不过，如果希望该分组能在浏览器中显示，我们还需要在 startup.cs 中定义的 docs 数组中增加 "演示分组" 名称

 static string[] docs = new[] { "未分类", "演示分组" };

4. 定义 api 接口友好名称

• 4.1 下面对每个接口进行友好名称显示的定义，通过编写 xml 注释，并在 summary 节点书写接口名称，即可自动显示到 api 文档上面

        /// <summary>
        ///  获取数组
        /// </summary>
        /// <remarks>
        /// <code>
        /// 输出参数：["value1", "value2"]
        /// </code>
        /// </remarks>
        /// <returns></returns>
        [httpget]
        public actionresult<ienumerable<string>> get()
        {
            return new string[] { "value1", "value2" };
        }

• 4.2 刷新网页，可以看到，接口友好名称已经显示出了了

结语

• swagger 基础应用可以帮助我们做到以下内容，现在就开始应用到程序中吧
• 自动生成 api 文档
• 对每个控制器进行分组
• 自动抓取开发人员编写的 xml 注释
• 在 api 文档界面进行即时测试
• 还有很多过滤等功能，下次有机会再试试

源码下载

https://files.cnblogs.com/files/viter/ron.swaggertest.zip