Swagger framework built from scratch eleven separate front and rear end NetCore2.2 (EF Core CodeFirst + Autofac) + Vue project using a

　A. Unused Swagger status

　　I believe both front-end or back-end developers developers, interface documentation are more or less have been tortured, often complain about the front end to the back-end interface documentation or inconsistent with the actual situation. Feel the back end interface documentation to write and maintenance will cost a lot of energy, often too late update. In fact, both front-end back-end call, back-end or back-end call, expect to have a good interface documentation. But the interface documentation for programmers, just as comments, often complain that the code written by someone else did not write notes, however, to write their own code for starting up, the most annoying, but also write comments. So just only by forcing everyone to regulate it is not enough, over time, an iterative version, interface documentation is often very easy to keep up with the code

　II. Use Swagger status

　　Swagger provides a visual display of the UI page description file, including call interface, the interface required parameters (header, body, url.params), the interface description parameter descriptions. The caller interface, test, project managers and so can be access to the relevant interfaces in the page and do some simple interface request. As long as the project to build the framework for Swagger configured, continuous iteration later time, it will only take a small price to maintain the code, interface documentation and Swagger profile. Because once the interface change occurs, the program re-deployment, interface documentation will re-generate the corresponding new document.

　III. How to use?

　　How to use Swagger in NetCore interface documentation project to generate it?

　　First, right-click on webApi startup project management Nuget package, install   Swashbuckle.AspNetCore  , and then to the   Startup  add a reference to   a using Swashbuckle.AspNetCore.Swagger; 

　　Add the following code process ConfigureServices

            #region Swagger

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "API Doc",
                    The Description = " Author: Levy_w_Wang " ,
                     // Terms of Service 
                    termsOfService = " None " ,
                     // Author Information 
                    Business Card = new new Business Card
                    {
                        Name = "levy",
                        Email = "[email protected]",
                        Url = " https://www.cnblogs.com/levywang "
                    },
                    // License 
                    License = new new License
                    {
                        Name = "tim",
                        Url = " https://www.cnblogs.com/levywang "
                    }
                });

                #region XmlComments

                var BASEPATH1 = Path.GetDirectoryName ( typeof (Program) .Assembly.Location); // get the application directory (absolute, not the working directory (platform), we suggest using this method to obtain the path)
                 // get the XML directory file information such as the comment display 
                var xmlComments = the Directory.GetFiles (BASEPATH1, " * .xml " , SearchOption.AllDirectories) .ToList ();

                foreach (var xmlComment in xmlComments)
                {
                    options.IncludeXmlComments(xmlComment);
                }
                #endregion

                options.DocInclusionPredicate((docName, description) => true);

                options.IgnoreObsoleteProperties (); // ignore methods Obsolete attribute 
                options.IgnoreObsoleteActions ();
                options.DescribeAllEnumsAsStrings();
            });
            #endregion

The above write cycle is because the project may have multiple controllers library, in order to exclude such a situation

Next, to the  Configure  method added:

            #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); // default document expanded mode 
            });

            #endregion

This uses  RoutePrefix  property, in order to change the original document directory open interfaces, the original path for the  Swagger / index.html  , now  /apidoc/index.html 

In this time you need to be output controller annotation libraries of properties provided the following information and add annotations on relevant

And then run up and open the local address plus   /apidoc/index.html   can see the effect,

Special note: If you open the following screen can be displayed, but prompt   Fetch errorInternal Server Error v1 / swagger.json   error, indicating that there are ways unspecified request method, such as HttpGet HttpPost HttpPut, etc., to find and identify, re-run on normal

 

  点击方法右上角的 Try it out ，试下调用接口，然后点击Exectue,执行查看结果，能得到后端方法返回结果就说明成功。

特别说明：有接口不需要展示出去的时候，可以在方法上添加属性 Obsolete ，这样就不会显示出来。 前提：有前面ConfigureServices中 后面的 忽略 有Obsolete 属性的方法 设置才行！！！

 

 最后可以看到接口返回数据正常，并且也能看到接口响应请求嘛等等信息，一个接口应该返回的信息也都有显示。

 

总结：

本文从为开发人员手写api文档的痛楚，从而引申出Swagger根据代码自动生成出文档和注释，

并且还可以将不需要的方法不显示等设置。然后进行了简单的测试使用 。

但是！！一般后端方法都有token等验证，需要在header中添加token、sid等字段来验证用户，保障安全性，

该设置将在下一章节中写！

 

以上若有什么不对或可以改进的地方，望各位指出或提出意见，一起探讨学习~

有需要源码的可通过此 GitHub 链接拉取 觉得还可以的给个 start 和点个 下方的推荐哦~~谢谢！