Преглед изворни кода

新增 Swagger Api文档按项目分组

zhontai пре 2 година
родитељ
комит
343edb5767

+ 1 - 1
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>

+ 9 - 1
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": {

+ 2 - 4
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 @@ new HostApp(new HostAppOptions
 			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);
 				});
 			});
 		}

+ 34 - 1
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 @@
         /// 地址
         /// </summary>
         public string Url { get; set; }
+
+        /// <summary>
+        /// 项目列表
+        /// </summary>
+        public List<ProjectConfig> Projects { get; set; }
     }
 
     /// <summary>
@@ -167,6 +174,32 @@
         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>

+ 37 - 0
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;
+                }
+            }
+        }
+    }
+}

+ 16 - 8
src/platform/ZhonTai.Admin/Core/HostApp.cs

@@ -29,7 +29,6 @@ using ZhonTai.Admin.Core.Auth;
 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 NLog.Web;
 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 @@ namespace ZhonTai.Admin.Core
             {
                 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 @@ namespace ZhonTai.Admin.Core
 
                     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 @@ namespace ZhonTai.Admin.Core
                 }
                 //禁止去除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 @@ namespace ZhonTai.Admin.Core
                 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

+ 35 - 0
src/platform/ZhonTai.Admin/ZhonTai.Admin.xml

@@ -290,6 +290,11 @@
             地址
             </summary>
         </member>
+        <member name="P:ZhonTai.Admin.Core.Configs.SwaggerConfig.Projects">
+            <summary>
+            项目列表
+            </summary>
+        </member>
         <member name="T:ZhonTai.Admin.Core.Configs.ApiUIConfig">
              <summary>
             新版Api文档配置
@@ -365,6 +370,31 @@
             操作日志
             </summary>
         </member>
+        <member name="T:ZhonTai.Admin.Core.Configs.ProjectConfig">
+            <summary>
+            项目配置
+            </summary>
+        </member>
+        <member name="P:ZhonTai.Admin.Core.Configs.ProjectConfig.Name">
+            <summary>
+            名称
+            </summary>
+        </member>
+        <member name="P:ZhonTai.Admin.Core.Configs.ProjectConfig.Code">
+            <summary>
+            编码
+            </summary>
+        </member>
+        <member name="P:ZhonTai.Admin.Core.Configs.ProjectConfig.Version">
+            <summary>
+            版本
+            </summary>
+        </member>
+        <member name="P:ZhonTai.Admin.Core.Configs.ProjectConfig.Description">
+            <summary>
+            描述
+            </summary>
+        </member>
         <member name="T:ZhonTai.Admin.Core.Configs.AppType">
             <summary>
             应用程序类型
@@ -585,6 +615,11 @@
             租户信息 admin:tenant:info:租户主键
             </summary>
         </member>
+        <member name="T:ZhonTai.Admin.Core.Conventions.ApiGroupConvention">
+            <summary>
+            Api分组约定
+            </summary>
+        </member>
         <member name="T:ZhonTai.Admin.Core.Dbs.MySqlDb">
             <summary>
             多数据库命名