SwaggerStudy/SwaggerStudy/Startup02.cs

using System;
using System.Linq;
using System.Threading.Tasks;
using System.Collections.Generic;

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
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;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using Swashbuckle.AspNetCore.SwaggerUI;


using SwaggerStudy.Services;

namespace SwaggerStudy
{
    /// <summary>
    /// 启用xml注释
    /// 1、打开项目文件xx.csproj，PropertyGroup节点内添加
    ///    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    ///    <NoWarn>$(NoWarn);1591</NoWarn>
    /// 2、Startup.cs的ConfigureServices方法中的services.AddSwaggerGen里，用setup.IncludeXmlComments()所有项目xml注释文件
    /// 3、WebApi方法与控制器中，使用xml注释
    /// 4、重新编译后使用
    /// </summary>
    public class Startup02
    {
        public Startup02(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services
                .AddControllers()
                //配置System.Text.Json选项
                .AddJsonOptions(jsonOption =>
                {
                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
                    jsonOption.JsonSerializerOptions.WriteIndented = true;
                    //允许(忽略)对象或数据末尾多余的逗号
                    jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
                    //自定义时间格式转换器
                    jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
                    //转义字符串编码器：直接显示中文
                    jsonOption.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
                });

            //注册Swagger生成器，定义一个或多个 Swagger 文档
            services.AddSwaggerGen(setup =>
            {
                #region 定义Swagger文档
                //name参数即为SwaggerUI中SwaggerEndpoint方法参数中的{documentName}
                //两者必须保持一致，否则异常
                setup.SwaggerDoc(name: "v1", new OpenApiInfo { Title = "Swagger学习", Version = "第一版" });
                #endregion

                #region 包含xml注释
                var xmlCommentFiles = System.IO.Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, $"SwaggerStudy*.xml", System.IO.SearchOption.TopDirectoryOnly);
                foreach (var xmlFile in xmlCommentFiles)
                {
                    //includeControllerXmlComments参数：是否启用控制器上的xml注释
                    setup.IncludeXmlComments(filePath: xmlFile, includeControllerXmlComments: true);
                }
                #endregion
            });

            services.AddTransient<StudentServer>();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            //启用 Swagger 中间件
            app.UseSwagger(setup=>
            { 
 
            });

            //启用 SwaggerUI 中间件
            app.UseSwaggerUI(setup => 
            {
                #region 添加Swagger JSON端点
                //必须包含{documentName}即是SwaggerDoc的name参数. 
                //默认为/swagger/{documentName}/swagger.json
                setup.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger学习第一版");
                #endregion
            });

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}