从壹开始前后端分离【 .NET Core2.0 +Vue2.0 】框架之四 || Swagger的使用 3.2

小灰灰 2021-09-19 03:48 167阅读 0赞

# WHY #

书接上文《[从零开始搭建自己的前后端分离【 .NET Core2.0 Api + Vue 2.0 】框架之三 || Swagger的使用 3.1][.NET Core2.0 Api _ Vue 2.0 _ _ Swagger_ 3.1]》，上文中只是简单的对如何使用Swagger作了介绍，而且最后也提出了几个问题，这里再重温下那几个问题

# BEFORE #

> 为何直接 F5 运行，首页还是无法加载？
> 
> 接口虽有，但是却没有相应的文字说明？
> 
> 项目开发中的实体类是如何在Swagger中展示的？
> 
> 对于接口是如何加权限验证的？

# HOW #

**1、设置swagger ui页面为首页**

在上一回中我们提到，我们直接F5运行项目，出现了系统默认页，

![image][]

虽然可以在输入/swagger后，顺利的访问swagger ui页，但是我们发现每次运行项目，都会默认访问api/values这个接口，我想要将启动页设为swagger（或者是任意一个页面），你就需要用到了

\*\***设置文件launchSettings.json** \*\*了：

![image][image 1]

![image][image 2]

然后你再一次F5 运行，就会发现不一样了，其他的配置，以及以后部署中的设置，我们会在以后的文章中都有提到。

**2、接下来，我们就需要解决第二个问题，如何增加文字说明，就是传说中的注释**

右键**项目名称=>属性=>生成**，勾选“输出”下面的“**xml文档文件**”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字

![image][image 3]

>  *  **.net core 2.1 新不同**
>  *  **生成的默认路径不一样了，没有了netcoreapp2.0文件夹**
> 
> ![img_133d06d3b04ee67223c879da0b6a17b8.png][]
> 
>

这个时候，先别忙着运行项目，作为老司机的我，只要是改代码或者配置文件，保存后，第一件事就是看看有没有错误，一看，咦~~~果然，虽然是警告，可以强迫症呀，一看还挺多

![image][image 4]

别慌！一看，哦！原来是swagger把一些接口方法都通过xml文件配置了，就是刚刚上文提到的，所以我们只需要加上方法注释就可以辣，可以左斜杠/，连续三下即可

![image][image 5]

现在呢，配置好了xml文件，接下来需要让系统启动的时候，去读取这个文件了，重新编辑Startup.cs，修改ConfigureServices函数：

![img_1c53668bcee393edac0d7b3b3daff1ae.gif][] ![img_405b18b4b6584ae338e0f6ecaf736533.gif][]

public void ConfigureServices(IServiceCollection services)
            {
                services.AddMvc();
    
                #region Swagger
                services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("v1", new Info
                    {
                        Version = "v0.1.0",
                        Title = "Blog.Core API",
                        Description = "框架说明文档",
                        TermsOfService = "None",
                        Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                    });
    
                    //就是这里
    
                    var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                    var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名
                    c.IncludeXmlComments(xmlPath,true);//默认的第二个参数是false，这个是controller的注释，记得修改
                });
                #endregion
            }

>  *  **.Net Core 2.1 新不同 感谢网友反馈@[风格不同][Link 1]，@[dannyjyc][]**
>  *  **获取项目路径的方式和2.0版本不一样**
> 
>     var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;
>          var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名
>          c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改

然后F5 运行，都加上了，感觉前端大佬再也不会说看不懂接口了，哈哈哈哈

![image][image 6]

接下来开始第三个问题：添加实体类说明注释

**新建一个.net core 类库Blog.Core.Model，注意是 .net core的类库**

**![image][image 7]**

** **

**新建一个Love的实体类**

/// <summary>
        /// 这是爱
        /// </summary>
        public class Love
        {
            /// <summary>
            /// id
            /// </summary>
            public int Id { get; set; }
            /// <summary>
            /// 姓名
            /// </summary>
            public string Name { get; set; }
            /// <summary>
            /// 年龄
            /// </summary>
            public int Age { get; set; }
        }

然后就是刚添加的类库中，在Model层项目，属性，中添加xml路径，添加注释（这里的步骤和API项目的添加方法一致，不会的请留言），然后在API项目中添加引用

![image][image 8]

image

![image.png][]

改写注入方法，并在控制器中参数引用

public void ConfigureServices(IServiceCollection services)
            {
                services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    
                #region Swagger
                services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("v1", new Info
                    {
                        Version = "v0.1.0",
                        Title = "Blog.Core API",
                        Description = "框架说明文档",
                        TermsOfService = "None",
                        Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                    });
                    //就是这里
    
                    var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;
                    var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名
                    c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
    
                    var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");//这个就是Model层的xml文件名
                    c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
                    c.IncludeXmlComments(xmlModelPath);
    
                });
    
                #endregion
    
            }

/// <summary>
           /// post
           /// </summary>
           /// <param name="love">model实体类参数</param>
            [HttpPost]
            public void Post(Love love)
            {
            }

*  **.net core 2.1 新不同**

> 注意，不能再HttpGet中，用实体类做参数，会报错

dang dang dang，就出来了

![image][image 9]

*  **.net core 2.1 新不同**

![img_f08b01cb123f6e436e800ba395f32f6d.png][]

# NEXT #

对于接口是如何加权限验证的？

让我们带着这些问题，继续浏览下一篇吧，Swagger 3.3 权限

# CODE #

[https://github.com/anjoy8/Blog.Core.git][https_github.com_anjoy8_Blog.Core.git]

[https://gitee.com/laozhangIsPhi/Blog.Core][https_gitee.com_laozhangIsPhi_Blog.Core]

[.NET Core2.0 Api _ Vue 2.0 _ _ Swagger_ 3.1]: https://www.cnblogs.com/laozhang-is-phi/p/9495624.html
[image]: /images/20210726/bf3e9d573b7742f5a72496517177163e.png
[image 1]: /images/20210726/1a511dedab604af9875a5cdadb875512.png
[image 2]: /images/20210726/6e61a3c59669487198d761cd6a5fd04a.png
[image 3]: /images/20210726/613e3ebeb6f145afb227931dab7d0a3a.png
[img_133d06d3b04ee67223c879da0b6a17b8.png]: /images/20210726/90fe25e6c2dc4a758323f339f27b7fbc.png
[image 4]: /images/20210726/e41fd0d439444c69ab323f3bff147569.png
[image 5]: /images/20210726/5d4373aab4b94ea1b74831a260ad9abf.png
[img_1c53668bcee393edac0d7b3b3daff1ae.gif]: https://yqfile.alicdn.com/img_1c53668bcee393edac0d7b3b3daff1ae.gif
[img_405b18b4b6584ae338e0f6ecaf736533.gif]: /images/20210726/20519adbb89243418b8e7b2c07ab5f1a.png
[Link 1]: https://www.cnblogs.com/zhoudidi/
[dannyjyc]: https://www.cnblogs.com/dannyjyc/
[image 6]: /images/20210726/643bd2495bfe4e7583417dca7aa970ec.png
[image 7]: /images/20210726/b29147925644454495ac251e698e139b.png
[image 8]: /images/20210726/bbe56a32e6ba4e599f6e4b895eb2c5d1.png
[image.png]: /images/20210726/7346326773dd40ab93d434d073a87506.png
[image 9]: /images/20210726/58bda4fb8d584adc8ff9ee71a63f52e6.png
[img_f08b01cb123f6e436e800ba395f32f6d.png]: /images/20210726/7b5c6f499a144fcd9b85cb7b6afe5046.png
[https_github.com_anjoy8_Blog.Core.git]: https://github.com/anjoy8/Blog.Core.git
[https_gitee.com_laozhangIsPhi_Blog.Core]: https://gitee.com/laozhangIsPhi/Blog.Core