• asp.net core 一个中小型项目实战的起手式——Swagger配置


    交流群:863563315

    一、Swagger是什么

    Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

    二、如何在项目中加入Swagger

    • Swagger安装引用

        右键Web项目依赖项>管理NuGet程序包>在搜索框输入"Swashbuckle.AspNetCore",然后单击安装

          

        

    • 添加并配置Swagger中间件

        首先在Startup类中引入Swagger:

            using Swashbuckle.AspNetCore.Swagger;

        将 Swagger 生成器添加到ConfigureServices 方法中的服务集合中:

                //注册Swagger生成器,定义一个和多个Swagger文档
                services.AddSwaggerGen(p =>
                {
                    p.SwaggerDoc("v1", new Info {Title = "数据管理器API文档", Version = "V1"});
                });

        在Configure方法中,启用中间件为生成的JSON文档和SwaggerUI提供服务:

                //启用中间件服务生成Swagger作为JSON终结点
                app.UseSwagger();
                //启用中间件服务对swagger-ui,指定Swagger JSON终结点
                app.UseSwaggerUI(p =>
                {
                    p.SwaggerEndpoint("/swagger/v1/swagger.json", "数据管理器API文档 v1"); 
                });

        启动应用,并跳转到 http://localhost:<port>/swagger/v1/swagger.json 生成的描述终结点的文档显示如下json格式。

        

        可在 /swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API文档,如下所示。

    •  为接口方法提供注释

      首先右键【解决方案资源管理器】中的项目,然后选【属性】

      查看“生成”选项卡的【输出】部分下的【XML 文档文件】框

      启用 XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息  例如,以下消息指示违反警告代码 1591。可以在进制显示警告中加入警告代码,这样不会再在错误列表中显示1591类型的警告了。

    在Swagger注册服务中增加:

                //注册Swagger生成器,定义一个和多个Swagger文档
                services.AddSwaggerGen(p =>
                {
                    p.SwaggerDoc("v1", new Info {Title = "数据管理器API文档", Version = "V1"});
    
                    // 为 Swagger JSON and UI设置xml文档注释路径
                    var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在绝对目录
                    var xmlPath = Path.Combine(basePath, "DataManager.Web.xml");//此处的文件名要对应到项目属性中生成的xml文件名
                    p.IncludeXmlComments(xmlPath);
                });

    在控制器目录下新增一个WebApi测试控制器,测试下效果

        [Route("api/[controller]/[action]")]
        [ApiController]
        public class SwaggerTestController : ControllerBase
        {
            /// <summary>
            /// 这是一个Swagger测试接口
            /// </summary>
            /// <returns></returns>
            [HttpGet]
            public IActionResult Test()
            {
                return new JsonResult(new {key = "Name", value = "test"});
            }
        }

    访问/swagger:

    好了,今天的在ASP.NET Core WebApi使用Swagger生成api说明文档的教程就到这里了。希望能够对大家学习在ASP.NET Core中使用Swagger生成api文档有所帮助!

  • 相关阅读:
    18.AutoMapper 之条件映射(Conditional Mapping)
    17.AutoMapper 之配置(Configuration)
    16.AutoMapper 之可查询扩展(Queryable Extensions)
    15. AutoMapper 之映射继承(Mapping Inheritance)
    14.AutoMapper 之依赖注入(Dependency Injection)
    13.AutoMapper 之映射前后(Before and After Map Action)
    12.AutoMapper 之Null替换(NullSubstitution)
    Windows 2012 系统汉化
    网站反屏蔽常见的六大方法
    Windows系统 本地文件如何复制到远程服务器
  • 原文地址:https://www.cnblogs.com/invoker-Fv/p/11393582.html
Copyright © 2020-2023  润新知