从零开始搭建前后端分离的NetCore2.2（EF Core CodeFirst+Autofac）+Vue的项目框架之十一Swagger使用一

程序员文章站 2023-11-14 09:20:10

一.未使用Swagger状况相信无论是前端开发人员还是后端开发人员，都或多或少都被接口文档折磨过，前端经常抱怨后端给的接口文档或与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程 ......

　一.未使用swagger状况

　　相信无论是前端开发人员还是后端开发人员，都或多或少都被接口文档折磨过，前端经常抱怨后端给的接口文档或与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了

　二.使用swagger状况

　　swagger 提供了一个可视化的ui页面展示描述文件，其中包括接口的调用，接口所需参数（header,body,url.params），接口说明，参数说明等。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。只要在项目框架搭建时，对swagger 进行了配置，后面持续迭代的时候，只会花很小代价去维护代码、接口文档以及swagger描述文件。因为一旦接口发生改变，程序重新部署，接口文档会重新生成对应新的文档。

　三.如何使用？

　　在netcore项目中怎么去使用swagger来生成接口文档呢？

　　首先在 webapi 启动项目上右键点击管理nuget程序包，安装 swashbuckle.aspnetcore ，然后到 startup 中添加引用 using swashbuckle.aspnetcore.swagger;

　　在configureservices方法中添加以下代码

            #region swagger

            services.addswaggergen(options =>
            {
                options.swaggerdoc("v1", new info
                {
                    version = "v1",
                    title = "api doc",
                    description = "作者:levy_w_wang",
                    //服务条款
                    termsofservice = "none",
                    //作者信息
                    contact = new contact
                    {
                        name = "levy",
                        email = "levy_w_wang@qq.com",
                        url = "https://www.cnblogs.com/levywang"
                    },
                    //许可证
                    license = new license
                    {
                        name = "tim",
                        url = "https://www.cnblogs.com/levywang"
                    }
                });

                #region xmlcomments

                var basepath1 = path.getdirectoryname(typeof(program).assembly.location);//获取应用程序所在目录（绝对，不受工作目录(平台)影响，建议采用此方法获取路径）
                //获取目录下的xml文件 显示注释等信息
                var xmlcomments = directory.getfiles(basepath1, "*.xml", searchoption.alldirectories).tolist();

                foreach (var xmlcomment in xmlcomments)
                {
                    options.includexmlcomments(xmlcomment);
                }
                #endregion

                options.docinclusionpredicate((docname, description) => true);

                options.ignoreobsoleteproperties();//忽略 有obsolete 属性的方法
                options.ignoreobsoleteactions();
                options.describeallenumsasstrings();
            });
            #endregion

上面写的循环是因为项目中可能有多个控制器类库，为的是排除这种情况

接下来，再到 configure 方法中添加：

            #region swagger

            app.useswagger(c => { c.routetemplate = "apidoc/{documentname}/swagger.json"; });
            app.useswaggerui(c =>
            {
                c.routeprefix = "apidoc";
                c.swaggerendpoint("v1/swagger.json", "contentcenter api v1");
                c.docexpansion(docexpansion.full);//默认文档展开方式
            });

            #endregion

这个时候在需要输出注释的控制器类库的属性中设置如下信息，并添加上相关注释

从零开始搭建前后端分离的NetCore2.2（EF Core CodeFirst+Autofac）+Vue的项目框架之十一Swagger使用一