使用Swagger制作WebApi的接口

Posted 2020-09-26 dzw159

首先，创建一个空的WebApi项目

之后，创建Controller，然后继承ApiController

之后呢，我们需要写个方法，当然，都是有返回值的，不能用return View()啥的（毕竟是返回数据用的接口）

然后，我们需要引用NuGet里头的 Swashbuckle、swagger.Net.UI

 

 

 

 注：引用完 Swashbuckle，会在App_Start里头生成一个 SwaggerConfig（用来配置Swagger参数的，强烈建议使用稳定版本的，我用了一下最新预发行版，结果没生成这个文件，之后再次引用下5.53的稳定版，丫丫的，也可能是这个文件需要后面才引用--在引用swagger.Net.UI之后）

配置参数：

using System.Web.Http;
using WebActivatorEx;
using wp3;
using Swashbuckle.Application;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace wp3
{
    /// <summary>
    /// Swagger配置
    /// </summary>
    public class SwaggerConfig
    {
　　　　 //加了这个
        private static string GetXmlCommentsPath()
        {
            return string.Format(@"{0}\\bin\\wp3.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }

        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration 
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "wp3");
                        c.IncludeXmlComments(GetXmlCommentsPath());//加了这个
　　　　　　　　　　 })
                .EnableSwaggerUi(c =>
                    {                   
 　　　　　　});
        }
    }
}

注意：上面的GetXmlCommentsPath  静态方法，是读取你这个项目bin目录下生成的 Xml（这个是你在Swagger里头注释的内容），

需要  右击你的项目->属性->生成，将XML文档文件  勾选起来，生成目录可以自己选择，当然  楼上的  SwaggerConfiger中的GetXmlCommentsPath  的路径也需要修改了

之后，去App_Start中，将楼上的两行注释掉（没有的话就算了，据说是因为：估计是nuget包中的代码没有更新导致这个异常出现）

 

然后，运行没看到，我就在代码头部加上个  Route("Default/Login")   路由地址

之后运行了，也显示出来了（包括没加这个路由的方法也显示出来了，个人猜测，应该是有大的改动之类的，才会更新--或者我没单一生成项目吧，外加清理解决方案）

最后呢？我们就可以运行期这个项目看看了

地址：http://localhost:5941/swagger/Ui/index    (你的local地址 +  /swagger/Ui/index )

结果如图：

后面，我们需要隐藏  辅助类方法（我们想要隐藏起来不显示）  的一些方法的话，可以在项目中创建一个  HiddenApiFilter.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using Swashbuckle.Swagger;
using System.Web.Http.Description;

namespace wp3.App_Start
{
    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
    public partial class HiddenApiAttribute : Attribute { }
    public class HiddenApiFilter: IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions)
            {
                if (Enumerable.OfType<HiddenApiAttribute>(apiDescription.GetControllerAndActionAttributes<HiddenApiAttribute>()).Any())
                {
                    string key = "/" + apiDescription.RelativePath;
                    if (key.Contains("?"))
                    {
                        int idx = key.IndexOf("?", StringComparison.Ordinal);
                        key = key.Substring(0, idx);
                    }
                    swaggerDoc.paths.Remove(key);
                }
            }
        }
    }
}

然后，配置  SwaggerConfig

在里头添加  

// 在接口类、方法标记属性 [HiddenApi]，可以阻止【Swagger文档】生成 
c.DocumentFilter<HiddenApiFilter>();

 

记得，事先要引用  你项目中的  HiddenApiFilter.cs

然后和，就可以在方法名 上面 +上一个  [HiddenApi]，这样子，项目 swagger  生成的XML就不会产生这个方法了

最后得到显示（隐藏掉了）

 

 

 

 

 

 

 后话，出现个状况，初始自带的  

 

 还存在，我后续看看怎么会出来的

 

后续补充：在HiddenApiFilter中进行默认接口的条件过滤 

    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
    public partial class HiddenApiAttribute : Attribute { }
    public class HiddenApiFilter : IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions)
            {
                var _key = "/" + apiDescription.RelativePath.TrimEnd(\'/\');
                // 过滤 swagger 自带的接口
                if (_key.Contains("/api/Swagger") && swaggerDoc.paths.ContainsKey(_key))
                    swaggerDoc.paths.Remove(_key);

                if (Enumerable.OfType<HiddenApiAttribute>(apiDescription.GetControllerAndActionAttributes<HiddenApiAttribute>()).Any())
                {
                    string key = "/" + apiDescription.RelativePath;
                    if (key.Contains("?"))
                    {
                        int idx = key.IndexOf("?", StringComparison.Ordinal);
                        key = key.Substring(0, idx);
                    }
                    swaggerDoc.paths.Remove(key);
                }
            }
        }
    }

 

设定默认启动页（运行默认显示页） 

 

 

 

 

 感谢：http://www.cnblogs.com/youzi1001/p/6156349.html

http://www.cnblogs.com/Leo_wl/p/5672430.html

 

https://blog.csdn.net/zhangkang823/article/details/89846656

https://www.cnblogs.com/yanweidie/p/5709113.html