基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

2019/04/10 10:10
阅读数 20

前言

         

  回顾上一篇文章《使用Swagger做Api文档 》,文中介绍了在.net core 3.1中,利用Swagger轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终实现生产自动生产API接口说明文档。文中结尾也留下了一个让大家思考的问题。在这里,我们重新回顾一下这几个问题

  1. 已经有接口了,但如何添加注释呢?
  2. 作为接口使用者,我们关心的是接口的返回内容和响应类型,那我们如何定义描述响应类型呢?
  3. 在项目开发中,使用的实体类,又如何在Swagger中展示呢?
  4. 在部署项目,引用Swagger既有文档又不需要额外部署,但是如何在开发环境中使用,而在生产环境中禁用呢?

开始

 一、为接口方法添加注释

1 . 按照下图所示 连点三次 / 即可添加文档注释

  如下所示

2.启用XML 注释

   右键web 项目名称=>属性=>生成,勾选“输出”下面的“xml文档文件”,系统会默认生成一个,如下图所示

 3.配置服务

  在之前注册的Swagger服务代码中,添加以下几行代码,引入xml文件

var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)
               //var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//这个就是刚刚配置的xml文件名
               // c.IncludeXmlComments(xmlPath);//默认的第二个参数是false,对方法的注释
                 c.IncludeXmlComments(xmlPath,true); // 这个是controller的注释

整体的代码如下:

public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Version = "V1",   //版本 
                    Title = $"XUnit.Core 接口文档-NetCore3.1",  //标题
                    Description = $"XUnit.Core Http API v1",    //描述
                    Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },  
                    License = new OpenApiLicense { Name = "艾三元许可证", Url = new Uri("http://i3yuan.cnblogs.com") }
                });
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)
               //var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//这个就是刚刚配置的xml文件名
                c.IncludeXmlComments(xmlPath);//默认的第二个参数是false,对方法的注释
                // c.IncludeXmlComments(xmlPath,true); //这个是controller的注释
            });
            services.AddControllers();
        }

 4.重新编译运行

  查看效果

注意:如果需要对控制器进行注释说明如下,可以将

c.IncludeXmlComments(xmlPath,true); 这个设置为true,显示效果如下:

 

二、描述响应类型

  接口使用者最关心的就是接口的返回内容和相应类型啦。下面展示一下201和400一个简单例子:

  我们需要在我们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]

  然后添加相应的状态说明:<response code="201">返回value字符串</response><response code="400">如果id为空</response>

  最终代码应该是这个样子:

/// <summary>
        /// values带id参数的get
        /// </summary>
        /// <param name="id"></param>
        /// <response code="201">返回value字符串</response>
        /// <response code="400">如果id为空</response>  
        /// <returns></returns>
        [HttpGet("{id}")]
        [ProducesResponseType(201)]
        [ProducesResponseType(400)]
        public string Get(int id)
        {
            return "value";
        }

效果如下:

三、实体类展示添加注释

 新建一个Movie的实体类,MovieModel

/// <summary>
    /// 这是电影实体类
    /// </summary>
    public class MovieModel
    {
        /// <summary>
        /// Id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 影片名称
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 类型
        /// </summary>
        public string Type { get; set; }
    }

在控制器中引入接口方法

/// <summary>
        /// post方式提交电影名称
        /// </summary>
        /// <param name="movie"></param>
        [HttpPost]
        public async Task<string> Post(MovieModel movie)
        {

            return movie.Name;
        }

效果如下:

四、在生产环境中禁用

  可以将Swagger的UI页面配置在Configure的开发环境之中

放到if(env.IsDevelopment())即可。

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", $"XUnit.Core V1");
                    c.RoutePrefix = string.Empty;     //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的
                                                      //路径配置,设置为空,表示直接在根域名(localhost:8001)访问该文件
                                                      // c.RoutePrefix = "swagger"; // 如果你想换一个路径,直接写名字即可,比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html
                });
                #endregion

            }
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

五、隐藏某些接口

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

[ApiExplorerSettings(IgnoreApi = true)]

六、忽视Swagger注释警告

 启用 XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息  例如,以下消息指示违反警告代码 1591:

 原来是swagger把一些 action 方法都通过xml文件配置了,如果你不想每一个方法都这么加注释,可以这么配置,在当前项目进行配置,可以忽略警告,记得在后边加上分号 ;1591

常见错误

 在Swagger使用的时候报错,无法看到列表,这里说下如何调试和主要问题:

1.找不到文件

请在浏览器 =》 F12 ==》 console 控制台 ==》点击错误信息地址

 

发现 是404 ,说明是找不到指定的文件,可以存在以下情况:

这是因为接口json文档定义和调用不是一个

1、定义:

ConfigureServices 方法中的  services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1", 

2、调用:

Configure 方法中的 app.UseSwaggerUI(c =>   调用  c.SwaggerEndpoint("/swagger/V1/swagger.json;

看看两者是否一致

 

 

 2. 500错误无法解析

直接链接http://localhost:xxxxx/swagger/v1/swagger.json,就能看到错误了

 这种可以存在以下情况:

1 . 接口请求的方式不明确: 少了[httpget]、[httpPost] 等,导致无法解析

总结

   1. 通过这一篇的整体学习,我们已经解决了上一篇文章留下的问题,也知道了怎样更好的使用Swagger进行开发接口文档,更加方便快捷的使用

   2. 从上篇的引用配置启动,到这一篇的升级改造,让接口文档更加通俗易懂。

   3. 关注公众号可以获取资料

    下载源码

 

原文出处:https://www.cnblogs.com/i3yuan/p/12542291.html

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部