使用Swagger自动生成ASP.NETCoreWebAPI的文档、在线帮助测试文档（ASP.NETCoreWebAPI自动生成文档）

 1 using System;
 2 using System.Collections.Generic;
 3 using System.Linq;
 4 using System.Threading.Tasks;
 5 using Microsoft.AspNetCore.Builder;
 6 using Microsoft.AspNetCore.Hosting;
 7 using Microsoft.Extensions.Configuration;
 8 using Microsoft.Extensions.DependencyInjection;
 9 using Microsoft.Extensions.Logging;
10 using Microsoft.Extensions.PlatformAbstractions;
11 using Swashbuckle.Swagger.Model;
12 
13 namespace dotNetCore_Test1
14 {
15 
16     public class Startup
17     {
18         public Startup(IHostingEnvironment env)
19         {
20             var builder = new ConfigurationBuilder()
21                 .SetBasePath(env.ContentRootPath)
22                 .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
23                 .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);
24 
25             if (env.IsEnvironment("Development"))
26             {
27                 // This will push telemetry data through Application Insights pipeline faster, allowing you to view results immediately.
28                 builder.AddApplicationInsightsSettings(developerMode: true);
29             }
30             builder.AddEnvironmentVariables();
31             COnfiguration= builder.Build();
32         }
33 
34         public IConfigurationRoot Configuration { get; }
35 
36         // This method gets called by the runtime. Use this method to add services to the container
37         public void ConfigureServices(IServiceCollection services)
38         {
39             // Add framework services.
40             services.AddApplicationInsightsTelemetry(Configuration);
41 
42             services.AddMvc();
43 
44             //services.AddLogging();
45 
46             // 注入的实现ISwaggerProvider使用默认设置
47             services.AddSwaggerGen();
48 
49             services.ConfigureSwaggerGen(optiOns=>
50             {
51                 options.SingleApiVersion(new Info
52                 {
53                     Version = "v1",
54                     Title = "测试ASP.NET Core WebAPI生成文档（文档说明）",
55                     Description = "A simple example ASP.NET Core Web API",
56                     TermsOfService = "None",
57                     COntact= new Contact { Name = "linyongjie", Email = "", Url = "https://docs.microsoft.com/zh-cn/aspnet/core/" },
58                     License = new License { Name = "Swagger官网", Url = "http://swagger.io/" }
59                 });
60 
61                 var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath; // 获取到应用程序的根路径
62                 options.IncludeXmlComments(basePath + "\\dotNetCore_Test1.xml");  //是需要设置 XML 注释文件的完整路径
63             });
64 
65             
66         }
67 
68         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline
69         public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
70         {
71             loggerFactory.AddConsole(Configuration.GetSection("Logging"));
72             loggerFactory.AddDebug();
73 
74             app.UseApplicationInsightsRequestTelemetry();
75 
76             app.UseApplicationInsightsExceptionTelemetry();
77 
78             app.UseMvc();
79 
80 
81             app.UseSwagger(); //使中间件服务生成Swagger作为JSON端点
82 
83             app.UseSwaggerUi();  //使中间件服务swagger-ui assets (HTML、Javascript、CSS等等)
84 
85         }
86     }
87 }

 1 using System;
 2 using System.Collections.Generic;
 3 using System.ComponentModel.DataAnnotations;
 4 using System.Linq;
 5 using System.Threading.Tasks;
 6 
 7 namespace dotNetCore_Test1.Models
 8 {
 9     
10     /// 

11     /// 用户模型
12     /// 
13     public class User
14     {
15         
16 
17         /// 

18         /// 年龄
19         /// 
20         public int Age { set; get; }
21 
22         /// 

23         /// 名称
24         /// 
25         [Required]  //此配置可以约束(Swagger )传进来的参数值 不能为空
26         public string Name { get; set; }
27 
28 
29         /// 

30         /// 性别
31         /// 
32         public string Sex { get; set; }
33     }
34 }

 1 using System;
 2 using System.Collections.Generic;
 3 using System.Linq;
 4 using System.Threading.Tasks;
 5 using Microsoft.AspNetCore.Mvc;
 6 
 7 namespace dotNetCore_Test1.Controllers
 8 {
 9     /// 

10     /// 测试 Swagger的 XML 注释
11     /// 
12     [Route("api/[controller]")]
13     public class ValuesController : Controller
14     {
15         /// 

16         /// 获得一个数组信息
17         /// 
18         /// 
19         [HttpGet]
20         public IEnumerable Get()
21         {
22             return new string[] { "value1", "value2" };
23         }
24 
25         /// 

26         /// 根据id获取信息
27         /// 
28         /// 主键唯一标识
29         /// 返回一个值
30         [HttpGet("{id}")]
31         public string Get(int id)
32         {
33             return "value";
34         }
35 
36         /// 

37         /// 添加一个用户
38         /// 
39         /// 
40         ///  
41         ///     POST /User
42         ///     {
43         ///        "Age": "年龄",
44         ///        "Name": "名称",
45         ///        "Sex": "性别
46         ///     }
47         /// 
48         /// 
49         /// 用户的json对象
50         /// 返回一个对象
51         /// 返回新创建的项目
52         /// 如果item是null
53         [HttpPost]
54         [ProducesResponseType(typeof(dotNetCore_Test1.Models.User), 201)]
55         [ProducesResponseType(typeof(dotNetCore_Test1.Models.User), 400)]
56         [HttpPost]
57         public IActionResult Post([FromBody]dotNetCore_Test1.Models.User item)
58         {
59             if (item == null)
60             {
61                 return BadRequest();
62             }
63             return Ok(item);
64         }
65 
66 
67 
68         
69         /// 

70         /// 删除一个对象
71         /// 
72         /// 
73         /// 这里可以写详细的备注
74         /// 
75         /// 主键id标识
76         [HttpDelete("{id}")]
77         public void Delete(int id)
78         {
79         }
80     }
81 }