• Net Core3.1 添加 Swagger


    一、为什么使用Swagger

    随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 

    前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。

    没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。

    书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。

    二、配置Swagger服务

    1、建一个net Core 3.1 的API项目,不演示了都会

    2、引用Nuget包

    右键项目中的 依赖项 -- > 管理 Nuget 程序包 --> 浏览 --> 搜索"Swashbuckle.AspNetCore" --> Install 安装最新版 

    安装完成后在项目的Nuget依赖里看到刚刚引入的Swagger

    3、配置服务

    打开Startup.cs类,编辑ConfigureServices方法

    // This method gets called by the runtime. Use this method to add services to the container.
            public void ConfigureServices(IServiceCollection services)
            {
                services.AddControllers();
    
                #region swagger
                services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                });
                #endregion
            }

    3、启动Http中间件

    编辑Configure方法

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
            {
                //判断是否是环境变量
                if (env.IsDevelopment())
                {
                    app.UseDeveloperExceptionPage();
                }
    
                #region swagger 
                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); 
                });
                #endregion
    
                app.UseRouting();
    
                app.UseAuthorization();
    
                app.UseEndpoints(endpoints =>
                {
                    endpoints.MapControllers();
                });
            }

    4、查看效果

    到这,已经完成swagger的添加,F5 运行调试,在域名后面输入/swagger,例如:http://localhost:54067/swagger/index.html 点击回车,就出来了

     

     

    5、设置默认直接首页访问 —— 生产环境

    每次手动在域名后边输入 /swagger ,很麻烦! 

    swagger 给我们提供了这个扩展,我们可以指定一个空字符,作为 swagger 的地址,在Configure中配置中间件:

               #region swagger 
                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    
                    c.RoutePrefix = "";//路径配置,设置为空,表示直接访问该文件,表示直接在根域名(localhost:8001)访问该文件
                    //这个时候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉, 然后直接访问localhost:8001/index.html即可        
                });
                #endregion

    然后再把我们上边的项目文件 launchSettings.json 的 launchUrl 给去掉就行了,这样我们无论是本地开发环境,还是生产环境,都可以默认首页加载了。

    这时候会发现没有注释,如果有注释可读性就很好了,下面开始实现注释

    6、显示注释

     1、给接口加一个注释

            /// <summary>
            /// ID 获取Json列表
            /// </summary>
            /// <param name="id"></param>
            /// <returns></returns>
            [HttpGet("{id}")]
            public IEnumerable<WeatherForecast> Get(int id)    

    2、右键点击项目---->属性------>生成------>勾选xml文档文件

    3、在startup类中的ConfigureServices 方法中的服务集合中添加如下代码

                #region swagger
                services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                    
                    var basePath = AppContext.BaseDirectory;
    
                    var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
                    c.IncludeXmlComments(xmlPath, true); //添加控制器层注释(true表示显示控制器注释)
                });
                #endregion

    4、运行项目并访问swaggerUI

     可以显示注释了

     

    7、对 Model 也添加注释说明

    新建一个.net core 类库Blog.Core.Model,注意是 .net core的类库,或者使用标准库也是可以的!(标准库可以在 NetCore 和 Framework 两个项目都可以跑)

    然后新建一个model

        /// <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; }
        }

    1、当前 api 层直接引用了 Blog.Core.Model 层;

    2、Blog.Core.Model 右键属性配置 xml

     3、导入model.xml到swagger

    // This method gets called by the runtime. Use this method to add services to the container.
            public void ConfigureServices(IServiceCollection services)
            {
                services.AddControllers();
    
                #region swagger
                services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                    
                    var basePath = AppContext.BaseDirectory;
    
                    var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
                    c.IncludeXmlComments(xmlPath, true); //添加控制器层注释(true表示显示控制器注释)
    
                    var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");
                    c.IncludeXmlComments(xmlModelPath, true);
                });
                #endregion
            }

    接口添加注释

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

    重新运行就出来了

     

    8、隐藏某些接口

    如果不想显示某些接口,直接在controller 上,或者action 上,增加特性

    [ApiExplorerSettings(IgnoreApi = true)]

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

    Post方法就不显示了

    三、结语

    下一篇 Swagger JWT 权限,给接口加权限验证

    
    
  • 相关阅读:
    《数据结构》第1章:绪论
    《计算机网络》第1章:计算机网络体系结构
    笔记迁移至:语雀
    最大似然估计和最大后验概率
    深度学习之最大似然估计
    k折交叉验证(matlab和python程序实现)
    matlab下打乱数组顺序
    线性回归
    梯度算法的Matlab实现
    梯度下降法
  • 原文地址:https://www.cnblogs.com/shuaichao/p/12374967.html
Copyright © 2020-2023  润新知