add docs

IGeekFan.AspNetCore.Knife4jUI.sln

@@ -5,8 +5,6 @@ VisualStudioVersion = 16.0.30330.147
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{929BB2D7-C678-4BE8-8AA9-F271A2AE4545}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "IGeekFan.AspNetCore.Knife4jUI", "src\IGeekFan.AspNetCore.SwaggerUI\IGeekFan.AspNetCore.Knife4jUI.csproj", "{4589D4A2-AAC0-40BD-8A8E-2EBB2B68DA22}"
-EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{75C51574-4CBD-403B-8182-8BF2A6DCFD43}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Basic", "test\Basic\Basic.csproj", "{88972F96-96D7-40A7-90DA-ED04C9ED9B33}"
@@ -22,16 +20,14 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{C146
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SwaggerUI_IndexStream_Knife4jUI_Demo", "samples\SwaggerUI_IndexStream_Knife4jUI_Demo\SwaggerUI_IndexStream_Knife4jUI_Demo.csproj", "{1D6FD5CA-5D58-4895-8545-A93099CE1AD4}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "IGeekFan.AspNetCore.Knife4jUI", "src\IGeekFan.AspNetCore.Knife4jUI\IGeekFan.AspNetCore.Knife4jUI.csproj", "{6C784918-BE29-4FEF-8AC3-9D34A38DE822}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
 		Release|Any CPU = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{4589D4A2-AAC0-40BD-8A8E-2EBB2B68DA22}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{4589D4A2-AAC0-40BD-8A8E-2EBB2B68DA22}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{4589D4A2-AAC0-40BD-8A8E-2EBB2B68DA22}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{4589D4A2-AAC0-40BD-8A8E-2EBB2B68DA22}.Release|Any CPU.Build.0 = Release|Any CPU
 		{88972F96-96D7-40A7-90DA-ED04C9ED9B33}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{88972F96-96D7-40A7-90DA-ED04C9ED9B33}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{88972F96-96D7-40A7-90DA-ED04C9ED9B33}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -44,15 +40,19 @@ Global
 		{1D6FD5CA-5D58-4895-8545-A93099CE1AD4}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{1D6FD5CA-5D58-4895-8545-A93099CE1AD4}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{1D6FD5CA-5D58-4895-8545-A93099CE1AD4}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6C784918-BE29-4FEF-8AC3-9D34A38DE822}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6C784918-BE29-4FEF-8AC3-9D34A38DE822}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6C784918-BE29-4FEF-8AC3-9D34A38DE822}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6C784918-BE29-4FEF-8AC3-9D34A38DE822}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
-		{4589D4A2-AAC0-40BD-8A8E-2EBB2B68DA22} = {929BB2D7-C678-4BE8-8AA9-F271A2AE4545}
 		{88972F96-96D7-40A7-90DA-ED04C9ED9B33} = {75C51574-4CBD-403B-8182-8BF2A6DCFD43}
 		{86A24FA0-E85D-4BDD-97D7-B990C50A40A9} = {75C51574-4CBD-403B-8182-8BF2A6DCFD43}
 		{1D6FD5CA-5D58-4895-8545-A93099CE1AD4} = {C146A419-15E0-4475-9623-706C5E2DCE0B}
+		{6C784918-BE29-4FEF-8AC3-9D34A38DE822} = {929BB2D7-C678-4BE8-8AA9-F271A2AE4545}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {9D77CCB4-F597-421B-9EF9-52D4B0AC382D}

README.md

@@ -30,7 +30,7 @@ CLI : dotnet add package IGeekFan.AspNetCore.Knife4jUI
 2.In the ConfigureServices method of Startup.cs, register the Swagger generator, defining one or more Swagger documents.
 
 ```
-using System.Reflection;
+using Microsoft.AspNetCore.Mvc.Controllers
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
 using IGeekFan.AspNetCore.Knife4jUI;
@@ -49,7 +49,8 @@ using IGeekFan.AspNetCore.Knife4jUI;
         });
         c.CustomOperationIds(apiDesc =>
         {
-            return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
+            var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
+            return  controllerAction.ControllerName+"-"+controllerAction.ActionName;
         });
     });
 ```
@@ -72,6 +73,24 @@ app.UseEndpoints(endpoints =>
 });
 ```
 
+5.更多功能
+
+为文档添加注释 在项目上右键--属性--生成
+
+![](https://pic.downk.cc/item/5f34161d14195aa59413f0fc.jpg)
+
+在AddSwaggerGen方法中添加如下代码
+
+```
+c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SwaggerDemo.xml"),true);
+```
+ 最后一个参数设置为true，代表启用控制器上的注释
+
+运行后如看不到控制器上注释显示，请点开文档管理->个性化设置，开启分组tag显示description说明属性
+
+![](https://pic.downk.cc/item/5f34171114195aa594142d2e.jpg)
+
+
 
 ### 🔎 效果图
 运行项目，打开 https://localhost:5001/index.html#/home
@@ -88,4 +107,4 @@ app.UseEndpoints(endpoints =>
 
 - [https://api.igeekfan.cn/swagger/index.html](https://api.igeekfan.cn/swagger/index.html)
 - [https://github.com/luoyunchong/lin-cms-dotnetcore](https://github.com/luoyunchong/lin-cms-dotnetcore)
-![image](https://pic.downk.cc/item/5f2fa97814195aa594cd5cfc.jpg)
+![image](https://pic.downk.cc/item/5f2fa97814195aa594cd5cfc.jpg)

samples/SwaggerUI_IndexStream_Knife4jUI_Demo/Startup.cs

@@ -1,17 +1,16 @@
 using System.Collections.Generic;
 using System.IO;
-using System.Reflection;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.FileProviders;
 using Microsoft.Extensions.Hosting;
 using Microsoft.OpenApi.Models;
-using Swashbuckle.AspNetCore.SwaggerGen;
 using Swashbuckle.AspNetCore.SwaggerUI;
 
 namespace Knife4jUIDemo
@@ -39,7 +38,8 @@ namespace Knife4jUIDemo
                 });
                 c.CustomOperationIds(apiDesc =>
                 {
-                    return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
+                    var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
+                    return controllerAction.ControllerName + "-" + controllerAction.ActionName;
                 });
             });
         }

src/IGeekFan.AspNetCore.Knife4jUI/IGeekFan.AspNetCore.Knife4jUI.csproj

@@ -11,12 +11,13 @@
 		<RepositoryType>git</RepositoryType>
 		<RepositoryUrl>https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI.git</RepositoryUrl>
 		<RootNamespace>IGeekFan.AspNetCore.Knife4jUI</RootNamespace>
-		<Version>0.0.2</Version>
+		<Version>0.0.3</Version>
 		<Company />
 		<Authors>igeekfan;xiaoym;</Authors>
 		<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 		<Copyright>Apache License 2.0</Copyright>
 		<PackageLicenseExpression></PackageLicenseExpression>
+		<AssemblyVersion>0.0.3.0</AssemblyVersion>
 	</PropertyGroup>
 
 	<ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.0' ">

src/IGeekFan.AspNetCore.Knife4jUI/index.html

@@ -6,19 +6,19 @@
     <meta name=viewport content="width=device-width,initial-scale=1">
     <link rel=icon href=favicon.ico>
     <title>%(DocumentTitle)</title>
-    <link href=knife4j/css/app.8f08f96a.css rel=preload as= style>
-    <link href=knife4j/js/app.c02977a4.js rel=preload as=script>
+    <link href=knife4j/css/app.b932f742.css rel=preload>
+    <link href=knife4j/js/app.920753bc.js rel=preload as=script>
     <link href=knife4j/js/chunk-vendors.e86fea24.js rel=preload as=script>
-    <link href=knife4j/css/app.8f08f96a.css rel=stylesheet>
+    <link href=knife4j/css/app.b932f742.css rel=stylesheet>
     %(HeadContent)
 </head>
 <body>
     <noscript><strong>We're sorry but knife4j-vue doesn't work properly without JavaScript enabled. Please enable it to continue.</strong></noscript><div id=app></div>
     <script src=knife4j/js/chunk-vendors.e86fea24.js></script>
-    <script src=knife4j/js/app.c02977a4.js></script>
+    <script src=knife4j/js/app.920753bc.js></script>
     <script>
         window.onload = function () {
-         
+
         }
     </script>
 </body>

src/IGeekFan.AspNetCore.SwaggerUI/IGeekFan - Backup.AspNetCore.Knife4jUI.csproj

@@ -1,40 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-	<PropertyGroup>
-		<TargetFrameworks>netstandard2.0;netcoreapp3.0</TargetFrameworks>
-		<Description>Middleware to expose an embedded version of the knife4j-vue-v3 from an ASP.NET Core application</Description>
-		<NoWarn>$(NoWarn);1591</NoWarn>
-		<GenerateDocumentationFile>true</GenerateDocumentationFile>
-		<PackageId></PackageId>
-		<PackageTags>swagger;documentation;discovery;help;webapi;aspnet;aspnetcore</PackageTags>
-		<PackageProjectUrl>https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI</PackageProjectUrl>
-		<RepositoryType>git</RepositoryType>
-		<RepositoryUrl>https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI.git</RepositoryUrl>
-		<RootNamespace>IGeekFan.AspNetCore.Knife4jUI</RootNamespace>
-		<Version>0.0.1</Version>
-		<Company />
-		<Authors />
-	</PropertyGroup>
-
-	<ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.0' ">
-		<PackageReference Include="Microsoft.AspNetCore.Routing" Version="2.1.0" />
-		<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.1.0" />
-		<PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="2.1.0" />
-		<PackageReference Include="System.Text.Json" Version="4.6.0" />
-	</ItemGroup>
-
-	<ItemGroup Condition=" '$(TargetFramework)' == 'netcoreapp3.0' ">
-		<FrameworkReference Include="Microsoft.AspNetCore.App" />
-	</ItemGroup>
-	<ItemGroup>
-		<PackageReference Include="IGeekFan.AspNetCore.Swagger" Version="5.5.1" />
-		<PackageReference Include="IGeekFan.AspNetCore.SwaggerGen" Version="5.5.1" />
-	</ItemGroup>
-
-	<ItemGroup>
-		<EmbeddedResource Include="knife4j/**/*" />
-		<EmbeddedResource Include="favicon.ico" />
-		<EmbeddedResource Include="index.html" />
-	</ItemGroup>
-
-</Project>

test/Basic/Basic.csproj

@@ -15,6 +15,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\src\IGeekFan.AspNetCore.SwaggerUI\IGeekFan.AspNetCore.Knife4jUI.csproj" />
+    <ProjectReference Include="..\..\src\IGeekFan.AspNetCore.Knife4jUI\IGeekFan.AspNetCore.Knife4jUI.csproj" />
   </ItemGroup>
 </Project>

test/Basic/Properties/launchSettings.json

@@ -1,21 +1,5 @@
 {
-  "$schema": "http://json.schemastore.org/launchsettings.json",
-  "iisSettings": {
-    "windowsAuthentication": false,
-    "anonymousAuthentication": true,
-    "iisExpress": {
-      "applicationUrl": "http://localhost:53224"
-    }
-  },
   "profiles": {
-    "IIS Express": {
-      "commandName": "IISExpress",
-      "launchBrowser": true,
-      "launchUrl": "",
-      "environmentVariables": {
-        "ASPNETCORE_ENVIRONMENT": "Development"
-      }
-    },
     "Basic": {
       "commandName": "Project",
       "launchBrowser": true,

test/Basic/Startup.cs

@@ -1,5 +1,4 @@
 using System;
-using System.Collections.Generic;
 using System.Globalization;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
@@ -10,13 +9,8 @@ using Microsoft.OpenApi.Models;
 using Basic.Swagger;
 using Microsoft.AspNetCore.Localization;
 using System.IO;
-using Microsoft.AspNetCore.Http;
-using Microsoft.Extensions.Options;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using Swashbuckle.AspNetCore.SwaggerGen;
-using System.Reflection;
 using IGeekFan.AspNetCore.Knife4jUI;
+using Microsoft.AspNetCore.Mvc.Controllers;
 
 namespace Basic
 {
@@ -56,9 +50,9 @@ namespace Basic
 
                 c.GeneratePolymorphicSchemas();
 
-                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Basic.xml"));
+                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Basic.xml"),true);
 
-                c.EnableAnnotations();
+                //c.EnableAnnotations();
                 c.AddServer(new OpenApiServer()
                 {
                     Url = "",
@@ -66,7 +60,8 @@ namespace Basic
                 });
                 c.CustomOperationIds(apiDesc =>
                 {
-                    return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
+                    var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
+                    return controllerAction.ControllerName + "-" + controllerAction.ActionName;
                 });
 
                 c.OrderActionsBy((apiDesc) => $"{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.HttpMethod}");
@@ -109,7 +104,7 @@ namespace Basic
 
             app.UseKnife4UI(c =>
             {
-                c.RoutePrefix = ""; // serve the UI at root
+                //c.RoutePrefix = ""; // serve the UI at root
                 c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
                 c.SwaggerEndpoint("/gp/api-docs", "<22><>¼ģ<C2BC><C4A3>");
             });

test/Knife4jUIDemo/Controllers/WeatherForecastController.cs

@@ -7,8 +7,11 @@ using Microsoft.Extensions.Logging;
 
 namespace Knife4jUIDemo.Controllers
 {
+    /// <summary>
+    /// 中文这是一个Get请求这是一个Get请求
+    /// </summary>
     [ApiController]
-    [Route("[controller]")]
+    [Route("api/WeatherForecast")]
     public class WeatherForecastController : ControllerBase
     {
         private static readonly string[] Summaries = new[]
@@ -23,6 +26,10 @@ namespace Knife4jUIDemo.Controllers
             _logger = logger;
         }
 
+        /// <summary>
+        /// 这是一个Get请求
+        /// </summary>
+        /// <returns></returns>
         [HttpGet]
         public IEnumerable<WeatherForecast> Get()
         {

test/Knife4jUIDemo/Knife4jUIDemo.csproj

@@ -1,15 +1,29 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
-  <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
-    <UserSecretsId>cb2091c6-d10b-4c1a-89c7-c72588c6ffe0</UserSecretsId>
-    <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
-  </PropertyGroup>
+	<PropertyGroup>
+		<TargetFramework>netcoreapp3.1</TargetFramework>
+		<UserSecretsId>cb2091c6-d10b-4c1a-89c7-c72588c6ffe0</UserSecretsId>
+		<DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
+	</PropertyGroup>
 
-  <ItemGroup>
-    <PackageReference Include="IGeekFan.AspNetCore.Knife4jUI" Version="0.0.1" />
-    <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.10.9" />
-  </ItemGroup>
+	<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
+		<DocumentationFile>Knife4jUIDemo.xml</DocumentationFile>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<PackageReference Include="Swashbuckle.AspNetCore" Version="5.5.1" />
+		<PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.10.9" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<ProjectReference Include="..\..\src\IGeekFan.AspNetCore.Knife4jUI\IGeekFan.AspNetCore.Knife4jUI.csproj" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<None Update="Knife4jUIDemo.xml">
+			<CopyToOutputDirectory>Always</CopyToOutputDirectory>
+		</None>
+	</ItemGroup>
 
 
 </Project>

test/Knife4jUIDemo/Knife4jUIDemo.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0"?>
+<doc>
+    <assembly>
+        <name>Knife4jUIDemo</name>
+    </assembly>
+    <members>
+        <member name="T:Knife4jUIDemo.Controllers.WeatherForecastController">
+            <summary>
+            中文这是一个Get请求这是一个Get请求
+            </summary>
+        </member>
+        <member name="M:Knife4jUIDemo.Controllers.WeatherForecastController.Get">
+            <summary>
+            这是一个Get请求
+            </summary>
+            <returns></returns>
+        </member>
+    </members>
+</doc>

test/Knife4jUIDemo/Properties/launchSettings.json

@@ -8,7 +8,7 @@
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       },
-      "applicationUrl": "https://localhost:5001;http://localhost:5000"
+      "applicationUrl": "http://localhost:5000"
     }
   }
 }

test/Knife4jUIDemo/Startup.cs

@@ -1,19 +1,12 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Reflection;
-using System.Threading.Tasks;
 using IGeekFan.AspNetCore.Knife4jUI;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
-using Microsoft.AspNetCore.HttpsPolicy;
-using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
-using Microsoft.Extensions.Logging;
 using Microsoft.OpenApi.Models;
-using Swashbuckle.AspNetCore.SwaggerGen;
+using System.IO;
 
 namespace Knife4jUIDemo
 {
@@ -40,8 +33,12 @@ namespace Knife4jUIDemo
                 });
                 c.CustomOperationIds(apiDesc =>
                 {
-                    return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
+                    var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
+                    return controllerAction.ControllerName + "-" + controllerAction.ActionName;
                 });
+
+                var filePath = Path.Combine(System.AppContext.BaseDirectory, "Knife4jUIDemo.xml");
+                c.IncludeXmlComments(filePath, true);
             });
         }
 
@@ -61,6 +58,11 @@ namespace Knife4jUIDemo
 
             app.UseSwagger();
 
+            app.UseSwaggerUI(c =>
+            {
+                c.SwaggerEndpoint("/v1/api-docs", "LinCms");
+            });
+
             app.UseKnife4UI(c =>
             {
                 c.RoutePrefix = ""; // serve the UI at root