ASP.NET Core使用Swagger

1. NuGet中引用“Swashbuckle.AspNetCore”组件。
2. Startup类中ConfigureServices方法添加如下代码配置：

 #region Swagger
            //注册Swagger生成器，定义一个和多个Swagger 文档

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "项目名.API",
                    Description = "描述",

                    //TermsOfService = "None",
                    //Contact = new Contact
                    //{
                    //    Name = "作者名",
                    //    Email = "邮箱",
                    //    Url = "链接地址"
                    //},
                    //License = new License
                    //{
                    //    Name = "许可证名字",
                    //    Url = "链接地址"
                    //}
                });

                // 为 Swagger JSON and UI设置xml文档注释路径

                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）

                var xmlPath = Path.Combine(basePath, "项目名.API.xml");
                c.IncludeXmlComments(xmlPath,true);//添加控制器层注释（true表示显示控制器注释）


                #region 添加右上角token输入框（需引用Swashbuckle.AspNetCore.Filters）
                //开启权限
                c.OperationFilter();
                c.OperationFilter();

                //在header中添加token
                c.OperationFilter();
                c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
                {
                    Description = "JWT授权(数据将在请求头中进行传递)直接在下面框中输入Bearer {token}(注意两者之间是一个空格) \"",
                    Name = "Authorization",//jwt默认的参数名称
                    In = ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
                    Type = SecuritySchemeType.ApiKey
                });
                #endregion

            });

            #endregion

 

1. Startup类中Configure方法添加如下代码配置：

            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                //c.RoutePrefix = string.Empty;  //如果跟目录显示SwaggerUI加上这句
            });

 

1. 控制器中定义方法测试示例：

 [Route("api/[controller]")]

    [ApiController]

    public class UserController : ControllerBase

    {

         /// 


         /// 获取token

         /// 

         /// 返回token

         ///描述

         ///主键

         ///入参为NULL

         ///异常

         [HttpGet]

         public ActionResult Get(int id)

         {

             return Ok(new { token = "token" });

         }

    }

    

5.启用XML 注释

选中项目“属性”->“生成”

说明：

http://localhost:/swagger/index.html  查看API文档

http://localhost:/swagger/v1/swagger.json。 生成的描述终结点的文档显示如下json格式。

 

注：如果swagger/index.html页面出现”Failed to load API definition“错误信息，请检查是否方法没有指定请求方式（HttpGet/HttpPost）。