ASP.NET Core WebApi使用Swagger生成API說明文檔【xml注釋版】

⒈新建ASP.NET Core WebAPi項目

⒉添加 NuGet 包

Install-Package Swashbuckle.AspNetCore

⒊Startup中配置

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Swashbuckle.AspNetCore.Swagger;

namespace SwaggerXmlDemo
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

            //注冊Swagger生成器，定義一個和多個Swagger 文檔
            services.AddSwaggerGen(option =>
            {
                //配置第一個Doc
                option.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "My API_1",
                    Description = "Document Api",
                    Contact = new Contact
                    {
                        Name = "fanqi",
                        Email = "[e-mail]",
                        Url = "https://www.coreqi.cn"                   
                    }
                });
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            //啟用中間件服務生成Swagger作為JSON終結點
            app.UseSwagger();

            //啟用中間件服務對swagger-ui，指定Swagger JSON終結點
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");
                //c.RoutePrefix = "swagger";  //默認
                c.RoutePrefix = string.Empty;
            });

            app.UseMvc();
        }
    }
}

⒋添加注釋信息

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

namespace SwaggerXmlDemo.Models
{
    /// <summary>
    /// 用戶實體類
    /// </summary>
    public class User
    {
        /// <summary>
        /// 用戶主鍵Id
        /// </summary>
        /// <example>1</example>
        public int id { get; set; }
        /// <summary>
        /// 用戶名
        /// </summary>
        /// <example>fanqi</example>
        public string username { get; set; }
        /// <summary>
        /// 用戶密碼
        /// </summary>
        /// <example>admin</example>
        public string password { get; set; }
        /// <summary>
        /// 用戶年齡
        /// </summary>
        /// <example>25</example>
        public int? age { get; set; }
        /// <summary>
        /// 用戶郵箱
        /// </summary>
        /// <example>[e-mail]</example>
        public string email { get; set; }
    }
}

 

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using SwaggerXmlDemo.Models;

namespace SwaggerDemo.Controllers
{
    /// <summary>
    /// 用戶Api控制器
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        /// <summary>
        /// 獲取系統用戶列表
        /// </summary>
        /// <remarks>
        /// Demo
        /// Get /api/user/get
        /// </remarks>
        /// <returns>系統用戶列表</returns>
        /// <response code="201">返回用戶列表</response>
        /// <response code="401">沒有權限</response>
        [HttpGet("get")]
        [ProducesResponseType(201)]
        [ProducesResponseType(401)]
        public IList<User> GetUsers()
        {
            return new List<User>
            {
                new User{ id = 1,username = "fanqi",password = "admin",age = 25,email = "[e-mail]"},
                new User{ id = 2,username = "gaoxing",password = "admin",age = 22,email = "[e-mail]"}
            };
        }

        /// <summary>
        /// 新建用戶
        /// </summary>
        /// <param name="user">新建用戶信息</param>
        /// <returns>是否創建成功信息</returns>
        [HttpPost("add")]
        public IActionResult CreateUser([FromForm] User user)
        {
            return Ok();
        }
    }
}

 

 

⒋啟用XML注釋

　　1.右鍵單擊“解決方案資源管理器”中的項目，然后選擇“屬性”

　　2.勾選“生成”選項卡“輸出”部分的“XML 文檔文件”框

右鍵生成的XML文件，選擇屬性。修改“復制到輸出目錄”為“始終復制”。

啟用 XML 注釋后會為未記錄的公共類型和成員提供調試信息將會出現很多CS1591警告信息。直接無視即可。

警告   CS1591	缺少對公共可見類型或成員“xxxxx”的 XML 注釋 指定了 /doc 編譯器選項，但是一個或多個構造沒有注釋。

如果有強迫症，可以按照下圖所示進行取消

注意上面生成的xml文檔文件的路徑，

 注意：

​ 1.對於 Linux 或非 Windows 操作系統，文件名和路徑區分大小寫。 例如，“SwaggerDemo.xml”文件在 Windows 上有效，但在 CentOS 上無效。

​ 2.獲取應用程序路徑，建議采用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

⒌為 Swagger JSON和UI設置xml文檔注釋路徑

 

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

            //注冊Swagger生成器，定義一個和多個Swagger 文檔
            services.AddSwaggerGen(option =>
            {
                //配置第一個Doc
                option.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "My API_1",
                    Description = "Document Api",
                    Contact = new Contact
                    {
                        Name = "fanqi",
                        Email = "[e-mail]",
                        Url = "https://www.coreqi.cn"                   
                    }
                });

                // 為 Swagger JSON and UI設置xml文檔注釋路徑
                //var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工作目錄影響，建議采用此方法獲取路徑）
                //var xmlPath = Path.Combine(basePath, "SwaggerXmlDemo.xml");
                var filePath = Path.Combine(System.AppContext.BaseDirectory, "SwaggerXmlDemo.xml");
                option.IncludeXmlComments(filePath);
            });
        }

 

⒍查看效果