Asp.net Core Web API使用Swagger创建帮助页

C#

浏览数:111

2019-8-30

AD:资源代下载服务

Asp.net Core Web API使用Swagger生成帮助页,Swagger使用内置技术创建一个API接口的帮助页面,页面不仅使API接口一目了然,而且把接口注释也显示在帮助页上,最大的特点是支持接口的在线测试。这些优点无疑使其比原先使用的Asp.net 内置的API帮助文档更受欢迎。

1引用Swagger NuGet packages

  • 使用程序包管理器控制台窗口:
    Install-Package Swashbuckle.AspNetCore
  • 使用NuGet管理界面安装
    右键项目>选择管理NuGet选项>在管理解决方案包里面搜索 Swashbuckle.AspNetCore>选择Swashbuckle.AspNetCore并安装。
    Swashbuckle.AspNetCore安装界面

2在项目中添加及设置ConfigureServices中间件

在Startup类的ConfigureServices方法添加如下代码,使项目中添加ConfigureServices中间件

  services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });

在Startup类的Configure,使项目能够使用ConfigureServices中间件

          app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                c.RoutePrefix = "";//路径配置,设置为空,表示直接访问该文件
            });

3运行调试

http://localhost:35030/swagger/ 不同的电脑可能会有不同的端口号

接口帮助文档


调试接口

4启用XML 注释

image.png

另外上图中,禁止显示警告中,添加1591 代码,可以过滤掉一些类名没有写注释的报警信息

在Startup类的Configure方法上,修改使用ConfigureServices中间件的调用方法

         services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",       
                    Title = "ToDo API",
                    Description = "A simple example ASP.NET Core Web API ",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "凌云木", Email = "825116693@qq.com", Url = "https://www.jianshu.com/u/79758fa3d8b0" },
                    License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
                });
                //为Swagger的JSON和UI设置XML注释
                var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "TodoApi.xml");
                c.IncludeXmlComments(xmlPath);
            });

在前面的代码中,AppicationBasePath获取应用程序的基本了路径。用来查找XML注释文件.TodoApi.xml仅适用于此示例中,引文生成的XML注释文件的名称基于应用程序的名称。

修改完运行调试

image.png

6 补充 (添加Model注释)

以上步骤做完生成的文档中,你会发现没有Model的注释,这不太完美,下面说下怎样添加添加Model注释

6.1新建一个.net core 类库ApiModel,注意是 .net core的类库

6.1 添加一个用户类

    /// <summary>
    /// 登录用户类
    /// </summary>
    public class User
    {
        /// <summary>
        /// 登陆用户名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 登录密码
        /// </summary>
        public string Pwd { get; set; }
    }

6.2设置XML文件输出

设置XML文件输出

6.3修改Startup中的Swagger配置

 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "凌云木 WebAPI",
                    Description = "A simple example ASP.NET Core Web API ",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "凌云木", Email = "88888888@qq.com", Url = "https://www.jianshu.com/u/79758fa3d8b0" },
                    License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
                });
                //为Swagger的JSON和UI设置XML注释
                var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "APIServer.xml");
                c.IncludeXmlComments(xmlPath,true);
                var xmlModelPath = Path.Combine(basePath, "ApiModel.xml");//这个就是Model层的xml文件名
                c.IncludeXmlComments(xmlModelPath);
            });

再次运行项目,Model的注释出来了

Mode注释

作者:凌雲木