Swagger UI 及Swashbuckle

Posted 2020-09-22 村_长

一、概念：

由Swagger网站可知，Swagger是展示RESTful API的简单而强大的方法，它为此API提供了强大的接口。

由Swashbuckle GitHub可知，Swashbuckle可将Swagger无缝添加到WebApi中！将ApiExplorer与Swagger/swagge-ui 合并可以给 API 用户带来丰富的探索、文件和操作体验。除Swagger生成器外，Swashbuckle还包含嵌入式版本的swagger-ui。

二、使用

1、使用包命令添加到项目

install-package Swashbuckle，会自动检测当前项目的环境添加依赖项。

2、生成xml文档文件

项目属性->勾选生成xml文档文件

3、修改SwaggerConfig文件，设置接口描述xml路径地址

c.IncludeXmlComments($"{System.AppDomain.CurrentDomain.BaseDirectory}/bin/{thisAssembly.GetName().Name}.XML");

4、汉化

a、添加自定义JS汉化包。

b、加载自定义汉化包：

//路径规则，项目命名空间.文件夹名称.js文件名称
c.Injectjavascript(thisAssembly, "Unisoft.WeChat.Content.swaggerui.swagger_lang.js");

具体参考：http://www.cnblogs.com/yanweidie/p/5709113.html

5、自定义参数及OAuth2授权

a、自定义参数代码

/// <summary>
    /// 自定义参数
    /// </summary>
    public class CustomParameterFilter : IOperationFilter
    {
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            if (operation.parameters == null)
                operation.parameters = new List<Parameter>();
            var filterPipeline = apiDescription.ActionDescriptor.GetFilterPipeline();
            //判断是否添加权限过滤器
            var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Instance).Any(filter => filter is IAuthorizationFilter);
            //判断是否允许匿名方法 
            var allowAnonymous = apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();

            //不含请求参数
            if (!operation.parameters.Any())
            {
                //判断是否为POST请求
                var isPost = apiDescription.HttpMethod.Method.ToLower() == "post";
                if (isPost)
                {
                    //添加POST参数
                    operation.parameters.Add(new Parameter
                    {
                        name = "body",
                        @in = "body",
                        description = "test",
                        required = false
                    });
                }
            }

            //添加认证参数
            if (isAuthorized && !allowAnonymous)
            {
                operation.parameters.Add(new Parameter
                {
                    name = "token",
                    @in = "query",
                    description = "认证参数",
                    required = true,
                    type = "string",
                    @default = "Unisoft@qodlALKJ8Fack123"
                });
            }
        }
    }

 b、使用自定义参数

 c.OperationFilter<CustomParameterFilter>();

具体参考：https://stackoverflow.com/questions/28033857/web-api-with-oauth-using-swagger-swashbuckle

 

其它资料参考：https://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-U#_articleTop