diff --git a/IGeekFan.AspNetCore.Knife4jUI.sln b/IGeekFan.AspNetCore.Knife4jUI.sln index 7430262..09ee4a0 100644 --- a/IGeekFan.AspNetCore.Knife4jUI.sln +++ b/IGeekFan.AspNetCore.Knife4jUI.sln @@ -11,6 +11,13 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{75C51574-4 EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Basic", "test\Basic\Basic.csproj", "{88972F96-96D7-40A7-90DA-ED04C9ED9B33}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{98C9AB6E-7179-4594-9703-BB0BB6D7949C}" + ProjectSection(SolutionItems) = preProject + README.md = README.md + EndProjectSection +EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Knife4jUIDemo", "test\Knife4jUIDemo\Knife4jUIDemo.csproj", "{86A24FA0-E85D-4BDD-97D7-B990C50A40A9}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -25,6 +32,10 @@ Global {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 {88972F96-96D7-40A7-90DA-ED04C9ED9B33}.Release|Any CPU.Build.0 = Release|Any CPU + {86A24FA0-E85D-4BDD-97D7-B990C50A40A9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {86A24FA0-E85D-4BDD-97D7-B990C50A40A9}.Debug|Any CPU.Build.0 = Debug|Any CPU + {86A24FA0-E85D-4BDD-97D7-B990C50A40A9}.Release|Any CPU.ActiveCfg = Release|Any CPU + {86A24FA0-E85D-4BDD-97D7-B990C50A40A9}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -32,6 +43,7 @@ Global 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} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {9D77CCB4-F597-421B-9EF9-52D4B0AC382D} diff --git a/README.md b/README.md index fc8f57d..3139723 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,86 @@ # IGeekFan.AspNetCore.Knife4jUI 一个支持.NET Core3.0,.NET Standard2.0的swagger ui 库：**knife4j UI**。 -## 相关类库 +## 相关依赖项 ### [knife4j](https://gitee.com/xiaoym/knife4j) - knife4j-vue-v3(不是vue3,而是swagger-ui-v3版本） ### [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) - -依赖项 - Swashbuckle.AspNetCore.Swagger - Swashbuckle.AspNetCore.SwaggerGen -``` - - - - -``` -## demo --[https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI/blob/master/test/Basic](https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI/blob/master/test/Basic) + +## Demo +- [Basic](https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI/blob/master/test/Basic) +- [Knife4jUIDemo](https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI/blob/master/test/Knife4jUIDemo) ## 快速开始 ### 安装包 +1.Install the standard Nuget package into your ASP.NET Core application. + ``` -Install-Package IGeekFan.AspNetCore.Knife4jUI -``` -或 -``` -dotnet add package IGeekFan.AspNetCore.Knife4jUI +Package Manager : Install-Package IGeekFan.AspNetCore.Knife4jUI +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.OpenApi.Models; +using Swashbuckle.AspNetCore.SwaggerGen; +using IGeekFan.AspNetCore.Knife4jUI; +``` ### ConfigureServices CustomOperationIds AddServer,必须的。 ``` services.AddSwaggerGen(c => - { - c.SwaggerDoc("v1",new OpenApiInfo{Title = "API V1",Version = "v1"}); - c.AddServer(new OpenApiServer() - { - Url = "", - Description = "vvv" - }); - c.CustomOperationIds(apiDesc => - { - return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null; - }); - }); + { + c.SwaggerDoc("v1",new OpenApiInfo{Title = "API V1",Version = "v1"}); + c.AddServer(new OpenApiServer() + { + Url = "", + Description = "vvv" + }); + c.CustomOperationIds(apiDesc => + { + return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null; + }); + }); ``` ### Configure ``` - app.UseSwagger(c => - { - - }); +app.UseSwagger(); - app.UseKnife4UI(c => - { - c.RoutePrefix = ""; // serve the UI at root - c.SwaggerEndpoint("/v1/api-docs", "V1 Docs"); - }); +app.UseKnife4UI(c => +{ + c.RoutePrefix = ""; // serve the UI at root + c.SwaggerEndpoint("/v1/api-docs", "V1 Docs"); +}); - app.UseEndpoints(endpoints => - { - endpoints.MapControllers(); - endpoints.MapSwagger("{documentName}/api-docs"); - }); +app.UseEndpoints(endpoints => +{ + endpoints.MapControllers(); + endpoints.MapSwagger("{documentName}/api-docs"); +}); ``` + + +### 效果图 +运行项目，打开 https://localhost:5001/index.html#/home + +![https://pic.downk.cc/item/5f2fa77b14195aa594ccbedc.jpg](https://pic.downk.cc/item/5f2fa77b14195aa594ccbedc.jpg) + + +### 更多配置请参考 + +- [https://github.com/domaindrivendev/Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) + + +### 更多项目 + +- [https://api.igeekfan.cn/swagger/index.html](https://api.igeekfan.cn/swagger/index.html) \ No newline at end of file diff --git a/test/Knife4jUIDemo/Controllers/WeatherForecastController.cs b/test/Knife4jUIDemo/Controllers/WeatherForecastController.cs new file mode 100644 index 0000000..8c58c18 --- /dev/null +++ b/test/Knife4jUIDemo/Controllers/WeatherForecastController.cs @@ -0,0 +1,39 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.Logging; + +namespace Knife4jUIDemo.Controllers +{ + [ApiController] + [Route("[controller]")] + public class WeatherForecastController : ControllerBase + { + private static readonly string[] Summaries = new[] + { + "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" + }; + + private readonly ILogger _logger; + + public WeatherForecastController(ILogger logger) + { + _logger = logger; + } + + [HttpGet] + public IEnumerable Get() + { + var rng = new Random(); + return Enumerable.Range(1, 5).Select(index => new WeatherForecast + { + Date = DateTime.Now.AddDays(index), + TemperatureC = rng.Next(-20, 55), + Summary = Summaries[rng.Next(Summaries.Length)] + }) + .ToArray(); + } + } +} diff --git a/test/Knife4jUIDemo/Knife4jUIDemo.csproj b/test/Knife4jUIDemo/Knife4jUIDemo.csproj new file mode 100644 index 0000000..0ae2591 --- /dev/null +++ b/test/Knife4jUIDemo/Knife4jUIDemo.csproj @@ -0,0 +1,15 @@ + + + + netcoreapp3.1 + cb2091c6-d10b-4c1a-89c7-c72588c6ffe0 + Linux + + + + + + + + + diff --git a/test/Knife4jUIDemo/Program.cs b/test/Knife4jUIDemo/Program.cs new file mode 100644 index 0000000..d9aa741 --- /dev/null +++ b/test/Knife4jUIDemo/Program.cs @@ -0,0 +1,26 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Hosting; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; + +namespace Knife4jUIDemo +{ + public class Program + { + public static void Main(string[] args) + { + CreateHostBuilder(args).Build().Run(); + } + + public static IHostBuilder CreateHostBuilder(string[] args) => + Host.CreateDefaultBuilder(args) + .ConfigureWebHostDefaults(webBuilder => + { + webBuilder.UseStartup(); + }); + } +} diff --git a/test/Knife4jUIDemo/Properties/launchSettings.json b/test/Knife4jUIDemo/Properties/launchSettings.json new file mode 100644 index 0000000..8eb6bc9 --- /dev/null +++ b/test/Knife4jUIDemo/Properties/launchSettings.json @@ -0,0 +1,14 @@ +{ + "$schema": "http://json.schemastore.org/launchsettings.json", + "profiles": { + "Knife4jUIDemo": { + "commandName": "Project", + "launchBrowser": true, + "launchUrl": "", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + }, + "applicationUrl": "https://localhost:5001;http://localhost:5000" + } + } +} \ No newline at end of file diff --git a/test/Knife4jUIDemo/Startup.cs b/test/Knife4jUIDemo/Startup.cs new file mode 100644 index 0000000..1ff2610 --- /dev/null +++ b/test/Knife4jUIDemo/Startup.cs @@ -0,0 +1,77 @@ +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.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using Microsoft.OpenApi.Models; +using Swashbuckle.AspNetCore.SwaggerGen; + +namespace Knife4jUIDemo +{ + public class Startup + { + public Startup(IConfiguration configuration) + { + Configuration = configuration; + } + + public IConfiguration Configuration { get; } + + // This method gets called by the runtime. Use this method to add services to the container. + public void ConfigureServices(IServiceCollection services) + { + services.AddControllers(); + services.AddSwaggerGen(c => + { + c.SwaggerDoc("v1", new OpenApiInfo { Title = "API V1", Version = "v1" }); + c.AddServer(new OpenApiServer() + { + Url = "", + Description = "vvv" + }); + c.CustomOperationIds(apiDesc => + { + return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null; + }); + }); + } + + // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. + public void Configure(IApplicationBuilder app, IWebHostEnvironment env) + { + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseHttpsRedirection(); + + app.UseRouting(); + + app.UseAuthorization(); + + app.UseSwagger(); + + app.UseKnife4UI(c => + { + c.RoutePrefix = ""; // serve the UI at root + c.SwaggerEndpoint("/v1/api-docs", "V1 Docs"); + }); + + app.UseEndpoints(endpoints => + { + endpoints.MapControllers(); + endpoints.MapSwagger("{documentName}/api-docs"); + }); + } + } +} diff --git a/test/Knife4jUIDemo/WeatherForecast.cs b/test/Knife4jUIDemo/WeatherForecast.cs new file mode 100644 index 0000000..417a51d --- /dev/null +++ b/test/Knife4jUIDemo/WeatherForecast.cs @@ -0,0 +1,15 @@ +using System; + +namespace Knife4jUIDemo +{ + public class WeatherForecast + { + public DateTime Date { get; set; } + + public int TemperatureC { get; set; } + + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); + + public string Summary { get; set; } + } +} diff --git a/test/Knife4jUIDemo/appsettings.Development.json b/test/Knife4jUIDemo/appsettings.Development.json new file mode 100644 index 0000000..8983e0f --- /dev/null +++ b/test/Knife4jUIDemo/appsettings.Development.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/test/Knife4jUIDemo/appsettings.json b/test/Knife4jUIDemo/appsettings.json new file mode 100644 index 0000000..d9d9a9b --- /dev/null +++ b/test/Knife4jUIDemo/appsettings.json @@ -0,0 +1,10 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + }, + "AllowedHosts": "*" +}