Swashbuckle.AspNetCore3.0的二次封装与使用

2023-10-07 06:20
文章标签 使用 封装 二次 swashbuckle aspnetcore3.0

本文主要是介绍Swashbuckle.AspNetCore3.0的二次封装与使用，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

关于 Swashbuckle.AspNetCore3.0

一个使用 ASP.NET Core 构建的 API 的 Swagger 工具。直接从您的路由，控制器和模型生成漂亮的 API 文档，包括用于探索和测试操作的 UI。
项目主页：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
项目官方示例：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/tree/master/test/WebSites

之前写过一篇Swashbuckle.AspNetCore-v1.10 的使用,现在 Swashbuckle.AspNetCore 已经升级到 3.0 了，正好开新坑(博客重构)重新封装了下，将所有相关的一些东西抽取到单独的类库中,尽可能的避免和项目耦合，使其能够在其他项目也能够快速使用。

运行示例

封装代码

待博客重构完成再将完整代码开源，参考下面步骤可自行封装

1. 新建类库并添加引用

我引用的版本如下

    <PackageReference Include="Microsoft.AspNetCore.Http.Abstractions" Version="2.1.1" /> <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.1" /> <PackageReference Include="Swashbuckle.AspNetCore" Version="3.0.0" />

2. 构建参数模型 CustsomSwaggerOptions.cs

    public class CustsomSwaggerOptions{/// <summary> /// 项目名称 /// </summary> public string ProjectName { get; set; } = "My API"; /// <summary> /// 接口文档显示版本 /// </summary> public string[] ApiVersions { get; set; } /// <summary> /// 接口文档访问路由前缀 /// </summary> public string RoutePrefix { get; set; } = "swagger"; /// <summary> /// 使用自定义首页 /// </summary> public bool UseCustomIndex { get; set; } /// <summary> /// UseSwagger Hook /// </summary> public Action<SwaggerOptions> UseSwaggerAction { get; set; } /// <summary> /// UseSwaggerUI Hook /// </summary> public Action<SwaggerUIOptions> UseSwaggerUIAction { get; set; } /// <summary> /// AddSwaggerGen Hook /// </summary> public Action<SwaggerGenOptions> AddSwaggerGenAction { get; set; } }

3. 版本控制默认参数接口实现 SwaggerDefaultValueFilter.cs

    public class SwaggerDefaultValueFilter : IOperationFilter{public void Apply(Swashbuckle.AspNetCore.Swagger.Operation operation, OperationFilterContext context) { // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/412 // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/413 foreach (var parameter in operation.Parameters.OfType<NonBodyParameter>()) { var description = context.ApiDescription.ParameterDescriptions.FirstOrDefault(p => p.Name == parameter.Name); if (description == null) return; if (parameter.Description == null) { parameter.Description = description.ModelMetadata.Description; } if (description.RouteInfo != null) { parameter.Required |= !description.RouteInfo.IsOptional; if (parameter.Default == null) parameter.Default = description.RouteInfo.DefaultValue; } } }

4. CustomSwaggerServiceCollectionExtensions.cs

    public static class CustomSwaggerServiceCollectionExtensions{public static IServiceCollection AddCustomSwagger(this IServiceCollection services) { return AddCustomSwagger(services, new CustsomSwaggerOptions()); } public static IServiceCollection AddCustomSwagger(this IServiceCollection services, CustsomSwaggerOptions options) { services.AddSwaggerGen(c => { if (options.ApiVersions == null) return; foreach (var version in options.ApiVersions) { c.SwaggerDoc(version, new Info { Title = options.ProjectName, Version = version }); } c.OperationFilter<SwaggerDefaultValueFilter>(); options.AddSwaggerGenAction?.Invoke(c); }); return services; } }

5. SwaggerBuilderExtensions.cs

    public static class SwaggerBuilderExtensions{public static IApplicationBuilder UseCustomSwagger(this IApplicationBuilder app) { return UseCustomSwagger(app, new CustsomSwaggerOptions()); } public static IApplicationBuilder UseCustomSwagger(this IApplicationBuilder app, CustsomSwaggerOptions options) { app.UseSwagger(opt => { if (options.UseSwaggerAction == null) return; options.UseSwaggerAction(opt); }); app.UseSwaggerUI(c => { if (options.ApiVersions == null) return; c.RoutePrefix = options.RoutePrefix; c.DocumentTitle = options.ProjectName; if (options.UseCustomIndex) { c.UseCustomSwaggerIndex(); } foreach (var item in options.ApiVersions) { c.SwaggerEndpoint($"/swagger/{item}/swagger.json", $"{item}"); } options.UseSwaggerUIAction?.Invoke(c); }); return app; } /// <summary> /// 使用自定义首页 /// </summary> /// <returns></returns> public static void UseCustomSwaggerIndex(this SwaggerUIOptions c) { var currentAssembly = typeof(CustsomSwaggerOptions).GetTypeInfo().Assembly; c.IndexStream = () => currentAssembly.GetManifestResourceStream($"{currentAssembly.GetName().Name}.index.html"); } }

6. 模型初始化

    private CustsomSwaggerOptions CURRENT_SWAGGER_OPTIONS = new CustsomSwaggerOptions(){ProjectName = "墨玄涯博客接口",ApiVersions = new string[] { "v1", "v2" },//要显示的版本 UseCustomIndex = true, RoutePrefix = "swagger", AddSwaggerGenAction = c => { var filePath = System.IO.Path.Combine(System.AppContext.BaseDirectory, typeof(Program).GetTypeInfo().Assembly.GetName().Name + ".xml"); c.IncludeXmlComments(filePath, true); }, UseSwaggerAction = c => { }, UseSwaggerUIAction = c => { } };

7. 在 api 项目中使用

添加对新建类库的引用，并在 webapi 项目中启用版本管理需要为输出项目添加 Nuget 包：Microsoft.AspNetCore.Mvc.Versioning，Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer (如果需要版本管理则添加)

我引用的版本如下

    <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="2.3.0" /> <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer" Version="2.2.0" />

Startup.cs 代码

    public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1); //版本控制 services.AddMvcCore().AddVersionedApiExplorer(o => o.GroupNameFormat = "'v'VVV"); services.AddApiVersioning(option => { // allow a client to call you without specifying an api version // since we haven't configured it otherwise, the assumed api version will be 1.0 option.AssumeDefaultVersionWhenUnspecified = true; option.ReportApiVersions = false; }); //custom swagger services.AddCustomSwagger(CURRENT_SWAGGER_OPTIONS); } // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } //custom swagger //自动检测存在的版本 // CURRENT_SWAGGER_OPTIONS.ApiVersions = provider.ApiVersionDescriptions.Select(s => s.GroupName).ToArray(); app.UseCustomSwagger(CURRENT_SWAGGER_OPTIONS); app.UseMvc(); }

关键代码拆解

action 方法的 xml 注释

new CustsomSwaggerOptions(){AddSwaggerGenAction = c =>{var filePath = System.IO.Path.Combine(System.AppContext.BaseDirectory, typeof(Program).GetTypeInfo().Assembly.GetName().Name + ".xml");//controller及action注释 c.IncludeXmlComments(filePath, true); } }

当然还需要生成xml，编辑解决方案添加(或者在vs中项目属性->生成->勾选生成xml文档文件)如下配置片段

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'"><DocumentationFile>.\项目名称.xml</DocumentationFile> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>.\项目名称.xml</DocumentationFile> </PropertyGroup>

目前.net core2.1我这会将此 xml 生成到项目目录，故可能需要将其加入.gitignore中。

版本控制

添加 Nuget 包：Microsoft.AspNetCore.Mvc.Versioning，Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
并在 ConfigureServices 中设置

    //版本控制services.AddMvcCore().AddVersionedApiExplorer(o => o.GroupNameFormat = "'v'VVV");services.AddApiVersioning(option =>{// allow a client to call you without specifying an api version// since we haven't configured it otherwise, the assumed api version will be 1.0option.AssumeDefaultVersionWhenUnspecified = true; option.ReportApiVersions = false; });

controller 使用

    /// <summary>/// 测试接口 /// </summary> [ApiVersion("1.0")] [Route("api/v{api-version:apiVersion}/test")] [ApiController] public class TestController : ControllerBase { }

自定义主题

将 index.html 修改为内嵌资源就可以使用GetManifestResourceStream获取文件流,使用此 html，可以自己使用var configObject = JSON.parse('%(ConfigObject)');获取到 swagger 的配置信息，从而根据此信息去写自己的主题即可。

    /// <summary>/// 使用自定义首页 /// </summary> /// <returns></returns> public static void UseCustomSwaggerIndex(this SwaggerUIOptions c) { var currentAssembly = typeof(CustsomSwaggerOptions).GetTypeInfo().Assembly; c.IndexStream = () => currentAssembly.GetManifestResourceStream($"{currentAssembly.GetName().Name}.index.html"); }

若想注入 css，js 则在 UseSwaggerUIAction 委托中调用对应的方法接口，官方文档

另外，目前 swagger-ui 3.19.0 并不支持多语言，不过可以根据需要使用 js 去修改一些东西
比如在 index.html 的 onload 事件中这样去修改头部信息

document.getElementsByTagName('span'
)[0].innerText = document.getElementsByTagName('span')[0] .innerText.replace('swagger', '项目接口文档') document.getElementsByTagName( 'span' )[1].innerText = document .getElementsByTagName('span')[1] .innerText.replace('Select a spec', '版本选择')

在找汉化解决方案时追踪到 Swashbuckle.AspNetCore3.0 主题时使用的swagger-ui 为 3.19.0，从issues2488了解到目前不支持多语言，其他的问题也可以查看此仓库
在使用过程中遇到的问题，基本上 readme 和 issues 都有答案，遇到问题多多阅读即可

参考文章

  • 官方示例
  • Asp.Net Core 中使用 Swagger，你不得不踩的坑

作者：易墨 
个人小站：http://www.yimo.link 
纯静态工具站点：http://tools.yimo.link/ 
说明：欢迎拍砖,不足之处还望园友们指出; 
迷茫大概是因为想的太多做的太少。

分类:  .net core
标签:  .net core,  swagger

 

转载于:https://www.cnblogs.com/webenh/p/11577749.html

这篇关于Swashbuckle.AspNetCore3.0的二次封装与使用的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！


http://www.chinasem.cn/article/156602。

相关文章

中文分词jieba库的使用与实景应用（一）

中文分词jieba库的使用与实景应用（一）

知识星球：https://articles.zsxq.com/id_fxvgc803qmr2.html 目录 一.定义： 精确模式（默认模式）： 全模式： 搜索引擎模式： paddle 模式（基于深度学习的分词模式）： 二 自定义词典 三.文本解析   调整词出现的频率 四. 关键词提取 A. 基于TF-IDF算法的关键词提取 B. 基于TextRank算法的关键词提取
阅读更多...
使用SecondaryNameNode恢复NameNode的数据

使用SecondaryNameNode恢复NameNode的数据

1）需求： NameNode进程挂了并且存储的数据也丢失了，如何恢复NameNode 此种方式恢复的数据可能存在小部分数据的丢失。 2）故障模拟 （1）kill -9 NameNode进程 [lytfly@hadoop102 current]$ kill -9 19886 （2）删除NameNode存储的数据（/opt/module/hadoop-3.1.4/data/tmp/dfs/na
阅读更多...
Hadoop数据压缩使用介绍

Hadoop数据压缩使用介绍

一、压缩原则 （1）运算密集型的Job，少用压缩 （2）IO密集型的Job，多用压缩 二、压缩算法比较 三、压缩位置选择 四、压缩参数配置 1）为了支持多种压缩/解压缩算法，Hadoop引入了编码/解码器 2）要在Hadoop中启用压缩，可以配置如下参数
阅读更多...
Makefile简明使用教程

Makefile简明使用教程

文章目录 规则makefile文件的基本语法：加在命令前的特殊符号：.PHONY伪目标: Makefilev1 直观写法v2 加上中间过程v3 伪目标v4 变量 make 选项-f-n-C Make 是一种流行的构建工具，常用于将源代码转换成可执行文件或者其他形式的输出文件(如库文件、文档等)。Make 可以自动化地执行编译、链接等一系列操作。 规则 makefile文件
阅读更多...
使用opencv优化图片（画面变清晰）

使用opencv优化图片（画面变清晰）

文章目录 需求影响照片清晰度的因素 实现降噪测试代码 锐化空间锐化Unsharp Masking频率域锐化对比测试 对比度增强常用算法对比测试 需求 对图像进行优化，使其看起来更清晰，同时保持尺寸不变，通常涉及到图像处理技术如锐化、降噪、对比度增强等 影响照片清晰度的因素 影响照片清晰度的因素有很多，主要可以从以下几个方面来分析 1. 拍摄设备 相机传感器：相机传
阅读更多...
pdfmake生成pdf的使用

pdfmake生成pdf的使用

实际项目中有时会有根据填写的表单数据或者其他格式的数据，将数据自动填充到pdf文件中根据固定模板生成pdf文件的需求 文章目录 利用pdfmake生成pdf文件1.下载安装pdfmake第三方包2.封装生成pdf文件的共用配置3.生成pdf文件的文件模板内容4.调用方法生成pdf 利用pdfmake生成pdf文件 1.下载安装pdfmake第三方包 npm i pdfma
阅读更多...
零基础学习Redis(10) -- zset类型命令使用

零基础学习Redis(10) -- zset类型命令使用

zset是有序集合，内部除了存储元素外，还会存储一个score，存储在zset中的元素会按照score的大小升序排列，不同元素的score可以重复，score相同的元素会按照元素的字典序排列。 1. zset常用命令 1.1 zadd  zadd key [NX | XX] [GT | LT]   [CH] [INCR] score member [score member ...]
阅读更多...
git使用的说明总结

git使用的说明总结

Git使用说明 下载安装(下载地址) macOS: Git - Downloading macOS Windows: Git - Downloading Windows Linux/Unix: Git (git-scm.com) 创建新仓库 本地创建新仓库：创建新文件夹，进入文件夹目录，执行指令 git init ，用以创建新的git 克隆仓库 执行指令用以创建一个本地仓库的
阅读更多...
【北交大信息所AI-Max2】使用方法

【北交大信息所AI-Max2】使用方法

BJTU信息所集群AI_MAX2使用方法 使用的前提是预约到相应的算力卡，拥有登录权限的账号密码，一般为导师组共用一个。 有浏览器、ssh工具就可以。 1.新建集群Terminal 浏览器登陆10.126.62.75 （如果是1集群把75改成66） 交互式开发 执行器选Terminal 密码随便设一个（需记住） 工作空间：私有数据、全部文件 加速器选GeForce_RTX_2080_Ti
阅读更多...
【Linux 从基础到进阶】Ansible自动化运维工具使用

【Linux 从基础到进阶】Ansible自动化运维工具使用

Ansible自动化运维工具使用 Ansible 是一款开源的自动化运维工具，采用无代理架构（agentless），基于 SSH 连接进行管理，具有简单易用、灵活强大、可扩展性高等特点。它广泛用于服务器管理、应用部署、配置管理等任务。本文将介绍 Ansible 的安装、基本使用方法及一些实际运维场景中的应用，旨在帮助运维人员快速上手并熟练运用 Ansible。 1. Ansible的核心概念
阅读更多...

Copyright China编程 23002807@qq.com

沪ICP备2023033072号-2