新增 Swagger Api文档按项目分组

zhontai · Jul 22, 2022 · 343edb5 · 343edb5
1 parent 8cb4db7
commit 343edb5
Show file tree

Hide file tree

Showing 7 changed files with 134 additions and 15 deletions.
diff --git a/build/pkg.props b/build/pkg.props
@@ -1,6 +1,6 @@
 <Project>
   <PropertyGroup>
-    <Version>2.1.0</Version>
+    <Version>2.1.1</Version>
 	<TargetFramework>net6.0</TargetFramework>
 	<GeneratePackageOnBuild>false</GeneratePackageOnBuild>
 	<GenerateDocumentationFile>true</GenerateDocumentationFile>

diff --git a/src/hosts/ZhonTai.Host/Configs/appconfig.json b/src/hosts/ZhonTai.Host/Configs/appconfig.json
@@ -14,7 +14,15 @@
     //启用
     "enable": true,
     //地址
-    "url": "http://localhost:8000"
+    "url": "http://localhost:8000",
+    "projects": [
+      {
+        "name": "中台Admin",
+        "code": "admin",
+        "version": "v2.1.0",
+        "description": ""
+      }
+    ]
   },
   //新版Api文档
   "apiUI": {

diff --git a/src/hosts/ZhonTai.Host/Program.cs b/src/hosts/ZhonTai.Host/Program.cs
@@ -1,9 +1,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
-using System.Linq;
 using ZhonTai.Admin.Core;
 using ZhonTai.Admin.Core.Configs;
-using ZhonTai.Admin.Core.Enums;
 using ZhonTai.Admin.Core.Startup;
 using ZhonTai.ApiUI;
 
@@ -21,9 +19,9 @@
 			app.UseApiUI(options =>
 			{
 				options.RoutePrefix = "swagger";
-				typeof(ApiVersion).GetEnumNames().OrderByDescending(e => e).ToList().ForEach(version =>
+				appConfig.Swagger.Projects?.ForEach(project =>
 				{
-					options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"ZhonTai.Host {version}");
+					options.SwaggerEndpoint($"/swagger/{project.Code.ToLower()}/swagger.json", project.Name);
 				});
 			});
 		}

diff --git a/src/platform/ZhonTai.Admin/Core/Configs/AppConfig.cs b/src/platform/ZhonTai.Admin/Core/Configs/AppConfig.cs
@@ -1,4 +1,6 @@
-namespace ZhonTai.Admin.Core.Configs
+using System.Collections.Generic;
+
+namespace ZhonTai.Admin.Core.Configs
 {
     /// <summary>
     /// 应用配置
@@ -82,6 +84,11 @@ public class SwaggerConfig
         /// 地址
         /// </summary>
         public string Url { get; set; }
+
+        /// <summary>
+        /// 项目列表
+        /// </summary>
+        public List<ProjectConfig> Projects { get; set; }
     }
 
     /// <summary>
@@ -167,6 +174,32 @@ public class VarifyCodeConfig
         public string[] Fonts { get; set; }// = new[] { "Times New Roman", "Verdana", "Arial", "Gungsuh", "Impact" };
     }
 
+    /// <summary>
+    /// 项目配置
+    /// </summary>
+    public class ProjectConfig
+    {
+        /// <summary>
+        /// 名称
+        /// </summary>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// 编码
+        /// </summary>
+        public string Code { get; set; }
+
+        /// <summary>
+        /// 版本
+        /// </summary>
+        public string Version { get; set; }
+
+        /// <summary>
+        /// 描述
+        /// </summary>
+        public string Description { get; set; }
+    }
+
     /// <summary>
     /// 应用程序类型
     /// </summary>

diff --git a/src/platform/ZhonTai.Admin/Core/Conventions/ApiGroupConvention.cs b/src/platform/ZhonTai.Admin/Core/Conventions/ApiGroupConvention.cs
@@ -0,0 +1,37 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.ApplicationModels;
+using ZhonTai.DynamicApi.Attributes;
+
+namespace ZhonTai.Admin.Core.Conventions;
+
+/// <summary>
+/// Api分组约定
+/// </summary>
+public class ApiGroupConvention : IControllerModelConvention
+{
+    public void Apply(ControllerModel controller)
+    {
+        if (controller.Attributes?.Count > 0)
+        {
+            foreach (var attribute in controller.Attributes)
+            {
+                if (attribute is AreaAttribute area)
+                {
+                    if (controller.ApiExplorer.GroupName.IsNull())
+                    {
+                        controller.ApiExplorer.GroupName = area.RouteValue?.ToLower();
+                    }
+                    break;
+                }
+                else if (attribute is DynamicApiAttribute dynamicApi)
+                {
+                    if (controller.ApiExplorer.GroupName.IsNull())
+                    {
+                        controller.ApiExplorer.GroupName = dynamicApi.Area?.ToLower();
+                    }
+                    break;
+                }
+            }
+        }
+    }
+}
diff --git a/src/platform/ZhonTai.Admin/Core/HostApp.cs b/src/platform/ZhonTai.Admin/Core/HostApp.cs
@@ -29,7 +29,6 @@
 using ZhonTai.Admin.Tools.Cache;
 using ZhonTai.Common.Helpers;
 using ZhonTai.Admin.Core.Db;
-using ZhonTai.Admin.Core.Enums;
 using ZhonTai.Admin.Core.Extensions;
 using ZhonTai.Admin.Core.Filters;
 using ZhonTai.Admin.Core.Logs;
@@ -46,6 +45,7 @@
 using Autofac.Extensions.DependencyInjection;
 using Microsoft.AspNetCore.Mvc;
 using ZhonTai.Admin.Core.Startup;
+using ZhonTai.Admin.Core.Conventions;
 
 namespace ZhonTai.Admin.Core
 {
@@ -294,12 +294,13 @@ private void ConfigureServices(IServiceCollection services, IWebHostEnvironment
             {
                 services.AddSwaggerGen(options =>
                 {
-                    typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
+                    appConfig.Swagger.Projects?.ForEach(project =>
                     {
-                        options.SwaggerDoc(version, new OpenApiInfo
+                        options.SwaggerDoc(project.Code.ToLower(), new OpenApiInfo
                         {
-                            Version = version,
-                            Title = "ZhonTai.Admin.Host"
+                            Title = project.Name,
+                            Version = project.Version,
+                            Description = project.Description
                         });
                         //c.OrderActionsBy(o => o.RelativePath);
                     });
@@ -314,7 +315,7 @@ private void ConfigureServices(IServiceCollection services, IWebHostEnvironment
 
                     options.ResolveConflictingActions(apiDescription => apiDescription.First());
                     options.CustomSchemaIds(x => x.FullName);
-                    options.DocInclusionPredicate((docName, description) => true);
+                    //options.DocInclusionPredicate((docName, description) => true);
 
                     string[] xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");
                     if (xmlFiles.Length > 0)
@@ -428,6 +429,12 @@ void controllersAction(MvcOptions options)
                 }
                 //禁止去除ActionAsync后缀
                 //options.SuppressAsyncSuffixInActionNames = false;
+
+                if (env.IsDevelopment() || appConfig.Swagger.Enable)
+                {
+                    //API分组约定
+                    options.Conventions.Add(new ApiGroupConvention());
+                }
             }
 
             var mvcBuilder = appConfig.AppType switch
@@ -573,10 +580,11 @@ private void ConfigureMiddleware(WebApplication app, IWebHostEnvironment env, IC
                 app.UseSwagger();
                 app.UseSwaggerUI(c =>
                 {
-                    typeof(ApiVersion).GetEnumNames().OrderByDescending(e => e).ToList().ForEach(version =>
+                    appConfig.Swagger.Projects?.ForEach(project =>
                     {
-                        c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"ZhonTai.Admin.Host {version}");
+                        c.SwaggerEndpoint($"/swagger/{project.Code.ToLower()}/swagger.json", project.Name);
                     });
+
                     c.RoutePrefix = "";//直接根目录访问，如果是IIS发布可以注释该语句，并打开launchSettings.launchUrl
                     c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);//折叠Api
                     //c.DefaultModelsExpandDepth(-1);//不显示Models

diff --git a/src/platform/ZhonTai.Admin/ZhonTai.Admin.xml b/src/platform/ZhonTai.Admin/ZhonTai.Admin.xml