.net core 2.1 Swagger 配置

1、先创建 .net core Web 应用程序,选择API

2、安装 Nuget 包：Swashbuckle.AspNetCore

Install-Package Swashbuckle.AspNetCore -Version 4.0.1

或者打开Nuget管理界面搜索Nlog.Web.AspNetCore(我安装的版本是V4.0.1)

3、注册依赖

通过修改Startup.cs里的ConfigureServices函数

  public void ConfigureServices(IServiceCollection services)
        {
  services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            #region 配置Swagger
            services.AddSwaggerGen(c =>
            {
                #region 顶部基础信息

                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "WebAPI",
                    Description = "API帮助文档",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "NinaMua", Email = "791016081@qq.com", Url = "http://www.cnblogs.com/NinaMua" }
                });
                #endregion

            });
            #endregion

        }    

ConfigureServices

4、使用中间件

 public void Configure(IApplicationBuilder app, IHostingEnvironment env,ILoggerFactory loggerFactory)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseHsts();
            }

            app.UseHttpsRedirection();

            loggerFactory.AddNLog();//添加NLog
            env.ConfigureNLog("nlog.config");//读取Nlog配置文件

            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
            });
            #endregion

            app.UseMvc();
        }

Configure

5、结果

 

当我们启动网页的时候，默认打开如下

把api/value 换成swagger

为了达到跑程序就默认打开swagger，需要去修改launchSetting.json

把launchUrl 换成Swagger

 "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

launchSetting.json

跑下程序可以看到默认页已经变成swagger了~

7.接口说明

点击项目属性，生成XML文档

同样的存放实体类的类库也生成XML文档

注意~两个XML文档需在同一bin路径下

给控制器添加说明

/*用标红的方式给控制器添加注解*/

/// <summary>
/// 登录
/// </summary>
/// <returns></returns>
[Route("Login")]
[HttpGet]
public ResponseMessage Login()
{

　　return new ResponseMessage
　　{
　　　　Code = 0,
　　　　Message = "123",
　　　　Data ="我是结果"
　　};

}

  /// <summary>
    /// 通用返回信息类
    /// </summary>
    public class ResponseMessage
    {
        /// <summary>
        /// 操作结果Code
        /// </summary>
        public int Code { get; set; }
        /// <summary>
        /// 返回信息
        /// </summary>
        public string Message { get; set; }
        /// <summary>
        /// 返回数据集合
        /// </summary>
        public object Data { get; set; }

    }

返回类

然后要去修改Startup类中的ConfigureServices方法

public void ConfigureServices(IServiceCollection services)
        {

   services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            #region 配置Swagger
            services.AddSwaggerGen(c =>
            {
                #region 顶部基础信息

                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "WebAPI",
                    Description = "API帮助文档",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "NinaMua", Email = "791016081@qq.com", Url = "http://www.cnblogs.com/NinaMua" }
                });
                #endregion

                #region 添加读取注释服务
                //添加对控制器的标签(描述)通过对SwaggerDocTag添加备注
                //c.DocumentFilter<SwaggerDocTag>();
                var basePath = AppDomain.CurrentDomain.BaseDirectory;

                var apiXmlPath = Path.Combine(basePath, "TestApi.xml");
                if (System.IO.File.Exists(apiXmlPath))
                    c.IncludeXmlComments(apiXmlPath, true);//控制器层注释（true表示显示控制器注释）

                var entityXmlPath = Path.Combine(basePath, "TestEntity.xml");
                if (System.IO.File.Exists(entityXmlPath))
                    c.IncludeXmlComments(entityXmlPath);//实体类注释
                #endregion

            });
            #endregion

        }

ConfigureServices

跑下程序看看

 8 接口权限

需在中间件中添加权限的东西~

   public void ConfigureServices(IServiceCollection services)
        {
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            #region 配置Swagger
            services.AddSwaggerGen(c =>
            {
                #region 顶部基础信息

                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "WebAPI",
                    Description = "API帮助文档",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "NinaMua", Email = "791016081@qq.com", Url = "http://www.cnblogs.com/NinaMua" }
                });
                #endregion

                #region 权限验证信息

                //添加一个必须的全局安全信息,和AddSecurityDefinition方法指定的方案名称要一致
                var security = new Dictionary<string, IEnumerable<string>> { { "Bearer", new string[] { } } };
                c.AddSecurityRequirement(security);

                c.AddSecurityDefinition("Bearer", new ApiKeyScheme
                {
                    Description = "格式|Bearer {token}",
                    Name = "Authorization",//jwt默认的参数名称
                    In = "header",//jwt默认在请求头中存放Authorization信息
                    Type = "apiKey"
                });

                #endregion

                #region 添加读取注释服务
                //添加对控制器的标签(描述)通过对SwaggerDocTag添加备注
                //c.DocumentFilter<SwaggerDocTag>();
                var basePath = AppDomain.CurrentDomain.BaseDirectory;

                var apiXmlPath = Path.Combine(basePath, "TestApi.xml");
                if (System.IO.File.Exists(apiXmlPath))
                    c.IncludeXmlComments(apiXmlPath, true);//控制器层注释（true表示显示控制器注释）

                var entityXmlPath = Path.Combine(basePath, "TestEntity.xml");
                if (System.IO.File.Exists(entityXmlPath))
                c.IncludeXmlComments(entityXmlPath);//实体类注释
                #endregion

            });
            #endregion

        }

ConfigureServices

修改完之后运行程序，发现在接口后多了一个小锁

点击那个锁弹出界面如下

先就这样把~~权限之后在搞把~