ASP.NET Core 2.2 基礎知識(十五) Swagger

 

安裝 Nuget 包

 

注冊 Swagger

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            //注冊 Swagger
            services.AddSwaggerGen(sg =>
            {
                sg.SwaggerDoc("refuge", new Swashbuckle.AspNetCore.Swagger.Info
                {
                    Title = "我的第一個 Swagger",
                    Version = "版本1"
                });
            });
        }

 

啟用 Swagger

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {

            //啟用 Swagger
            app.UseSwagger();
            app.UseSwaggerUI(s =>
            {
                s.SwaggerEndpoint("/swagger/refuge/swagger.json", "My API 1.0.1");//注意,中間那段的名字 (refuge) 要和 上面 SwaggerDoc 方法定義的 名字 (refuge)一樣
                s.RoutePrefix = string.Empty; //默認值是 "swagger" ,需要這樣請求:https://localhost:44384/swagger
            });

　　　　　　　......
        }

 

修改 launchSetting.json 文件中指定的默認啟動路徑

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:56872",
      "sslPort": 44384
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      //"launchUrl": "api/values",
      "launchUrl": "",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "SwashbuckleDemo2": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "api/values",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

CTRL+F5 啟動項目

 

 下面,我們來豐富一下這個 Swagger

新建一個 PersonsController 

 

 

 

編輯該項目屬性:

 

 給 Action 添加 XML 注釋:

 

添加 Swagger 的XML注釋提示功能 

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            //注冊 Swagger
            services.AddSwaggerGen(sg =>
            {
                sg.SwaggerDoc("refuge", new Swashbuckle.AspNetCore.Swagger.Info
                {
                    Title = "我的第一個 Swagger",
                    Version = "版本1"
                });
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); sg.IncludeXmlComments(xmlPath);
            });
        }

 

 

 

設置返回結果

 

 

Person 類如下:

    /// <summary>
    /// 人
    /// </summary>
    public class Person
    {
        /// <summary>
        /// 編號
        /// </summary>
        public int Id { get; set; }

        /// <summary>
        /// 姓名
        /// </summary>
        [Required(ErrorMessage = "姓名不能為空")]

        public string Name { get; set; }

        /// <summary>
        /// 年齡
        /// </summary>
        public int Age { get; set; }
    }

 

 

 

-----------------------------------------------------------------------------------

下面是回復網友的評論:

 

        /// <summary>
        /// 測試入參是實體,返回值也是實體
        /// </summary>
        /// <param name="person">人</param>
        /// <returns></returns>
        [HttpPost]
        [ProducesResponseType(typeof(Person), 250)]//返個250給前端
        public Person GetPerson([FromBody]Person person)
        {
            return person;
        }