03.01 asp.net core使用swagger生成api網頁文檔的具體步驟

.Net Core中有兩個集成NSwag的包，分別為Swashbuckle和NSwag。兩者的配置大同小異。這裡以NSwag為例。

一、前期準備

1、初始化asp.net core 測試項目

新建asp.net core項目，此處略過；新建apicontroller，並編寫測試代碼；

<code>    [Route("api/[controller]")]
    [ApiController]
    public class UserApiController : ControllerBase
    {
        /// <summary>
        /// 獲取用戶信息，根據用戶id
        /// /<summary>
        /// <param>用戶id
        /// <returns>
        [HttpGet("getuser/{id}")]
        public ActionResult GetUser(int id)
        {
            User u = new User { Id=1,Name="Jack"};
            return Ok(new { ok = true, data = u });
        }
        /// <summary>
        /// 添加用戶
        /// /<summary>
        /// <param>用戶信息
        /// <returns>
        [HttpPost("postuser")]
        public ActionResult AddUser([FromBody]User user)
        {
            return Ok(new { ok = true, data = user });
        }
    }/<code>

<code>    public class User 

    { 
        /// <summary>
        /// 用戶id
        /// /<summary>
        public int Id { get; set; }
        /// <summary>
        /// 用戶姓名
        /// /<summary>
        public string Name { get; set; }
    }/<code>

2、使用nuget安裝 NSwag.AspNetCore

方式一：通過vs圖形界面安裝；

方式二：通過nuget 命令安裝：

<code>Install-Package NSwag.AspNetCore/<code>

二、配置Swagger

1、添加並配置 Swagger 中間件

• 在應用的Startup類中的ConfigureServices 方法中，註冊所需的 Swagger 服務：

<code>        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllersWithViews();
            
            // Register the Swagger services
    \t\tservices.AddSwaggerDocument()
        }/<code>

• 在Startup類中的Configure 方法中，啟用中間件為生成的 Swagger 規範和 Swagger UI 提供服務：

<code>public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}/<code>

• 啟動應用。 轉到：
  http://localhost:/swagger，以查看 Swagger UI。
  http://localhost:/swagger/v1/swagger.json，以查看 Swagger 規範。

2、自定義 API 文檔

API 信息和說明

在 Startup.ConfigureServices 方法中，傳遞給 AddSwaggerDocument 方法的配置操作會添加諸如作者、許可證和說明的信息：

<code>\t\tpublic void ConfigureServices(IServiceCollection services)
        {
            //services.AddControllers();
            services.AddControllersWithViews();

            services.AddSwaggerDocument(config =>
            {
                config.PostProcess = document =>
                {
                    document.Info.Version = "v1";
                    document.Info.Title = "UserManageApp API";
                    document.Info.Description = "A simple ASP.NET Core web API";
                    document.Info.TermsOfService = "None";
                    document.Info.Contact = new NSwag.OpenApiContact
                    {
                        Name = "張三",
                        Email = string.Empty,
                        Url = "https://example.com"
                    };
                    document.Info.License = new NSwag.OpenApiLicense
                    {
                        Name = "Use under LICX",
                        Url = "https://example.com/license"
                    };
                };
            });
        }/<code>

Swagger UI 顯示版本的信息：

XML 註釋

若要啟用 XML 註釋，請執行以下步驟：以windows先使用vs為例：

• 在“解決方案資源管理器”中右鍵單擊該項目，然後選擇“編輯 <project>.csproj” 。/<project>
• 手動將突出顯示的行添加到 .csproj 文件 ：

三、參考

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-3.0&tabs=visual-studio

*以上講解知識入門級的，能大體使用起來，能滿足一般性需求；

閱讀更多 ICodeYou 的文章

關鍵字: 網頁 Info core