从壹开始前后端分离【 .NET Core2.0 +Vue2.0 】框架之四 || Swagger的使用 3.2-阿里云开发者社区

开发者社区> laozhang_is_phi> 正文

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

简介: WHY 书接上文《从零开始搭建自己的前后端分离【 .NET Core2.0 Api + Vue 2.0 】框架之三 || Swagger的使用 3.1》,上文中只是简单的对如何使用Swagger作了介绍,而且最后也提出了几个问题,这里再重温下那几个问题 BEFORE 为何直接 F5 运行,...
+关注继续查看

WHY

书接上文《从零开始搭建自己的前后端分离【 .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
 

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

 

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

 

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

image
 
  • .net core 2.1 新不同
  • 生成的默认路径不一样了,没有了netcoreapp2.0文件夹

 

 

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

image
 

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

image
 

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

 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
        }
View Code

 

  • .Net Core 2.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
 

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

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

 

image
 
新建一个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

 

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
 
  • .net core 2.1 新不同

 

NEXT

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

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

CODE

https://github.com/anjoy8/Blog.Core.git

https://gitee.com/laozhangIsPhi/Blog.Core

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
CHB
小程序开发:用原生还是选框架(wepy/mpvue/taro/uni-app)-- 第1季
uni-app团队,针对每个小程序开发框架的最新升级版本,每季度发布一次实时、深度的评测报告,给开发者提供选型参考
4050 0
从零开始学习 asp.net core 2.1 web api 后端api基础框架(一)-环境介绍
原文:从零开始学习 asp.net core 2.1 web api 后端api基础框架(一)-环境介绍 版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/kingyumao/article/details/81531757 学习http://www.cnblogs.com/cgzl/p/7637250.html的笔记。
1903 0
从头编写 asp.net core 2.0 web api 基础框架 (2)
原文:从头编写 asp.net core 2.0 web api 基础框架 (2) 上一篇是: http://www.cnblogs.com/cgzl/p/7637250.html Github源码地址是: https://github.
761 0
基于ASP.Net Core开发的一套通用后台框架
基于ASP.Net Core开发的一套通用后台框架写在前面这是本人在学习的过程中搭建学习的框架,如果对你有所帮助那再好不过。如果您有发现错误,请告知我,我会第一时间修改。知其然,知其所以然,并非重复的造轮子。
18138 0
从零开始学习 asp.net core 2.1 web api 后端api基础框架(三)-创建Data Transfer Object
原文:从零开始学习 asp.net core 2.1 web api 后端api基础框架(三)-创建Data Transfer Object 版权声明:本文为博主原创文章,未经博主允许不得转载。
822 0
从零开始学习 asp.net core 2.1 web api 后端api基础框架(四)-创建Controller
原文:从零开始学习 asp.net core 2.1 web api 后端api基础框架(四)-创建Controller 版权声明:本文为博主原创文章,未经博主允许不得转载。
1038 0
+关注
laozhang_is_phi
攻城狮一枚; 乐于分享新知识
16
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载