AspnetCore WebApi使用Swagger簡單入門

時間 2019-12-10

標籤 aspnetcore webapi 使用 swagger 簡單入門简体版

原文原文鏈接

微軟官網入門：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.2git

Swagger是一個支持Rest Api的，用於可視化。也就是說你的WebApi必須遵循RestApi架構風格，不然是沒法生成Api文檔的github

依賴包：web

Swashbuckle.Aspnetcore：用於生成Swagger文檔json

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer：用戶版本控制api

由於接口會不斷的升級，迭代，因此必然會有版本控制，這樣新的版本不會影響就的版本架構

因此，我這裏一開始就會搭建一個版本控制app

建立Api項目，默認會有Value控制器，而後分別添加v1和v2文件夾，建立ManagerControlleride

添加版本控制類，添加CustomApiVersion類測試

namespace SwaggerApi.SwaggerHelper
{
    /// <summary>
    /// 自定義版本
    /// </summary>
    public class CustomApiVersion
    {
        /// <summary>
        /// Api接口版本 自定義
        /// </summary>
        public enum ApiVersions
        {
            /// <summary>
            /// v1 版本
            /// </summary>
            v1 = 1,
            /// <summary>
            /// v2 版本
            /// </summary>
            v2 = 2,
        }
    }
}

而後在控制器上經過ApiExplorerSettings分組，就是說明該控制器是那個版本組ui

建立用於測試的實體類：

namespace SwaggerApi.Models
{
    public class Student
    {
        /// <summary>
        /// 用戶Id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 用戶姓名
        /// </summary>
        /// <example>示例</example>
        public string UserName { get; set; }
        /// <summary>
        /// 用戶名年齡
        /// </summary>
        public int Age { get; set; }

        /// <summary>
        /// 性別
        /// <remarks>
        /// 0：男
        /// 1：女
        /// 2：其餘
        /// </remarks>
        /// </summary>

        public Gender Gender { get; set; }
    }

    public enum Gender
    {
        /// <summary>
        /// 男
        /// </summary>
        M = 0,
        /// <summary>
        /// 女
        /// </summary>
        F = 1,
        /// <summary>
        /// 其餘
        /// </summary>
        O = 2
    }

}

註冊中間件:

services.AddSwaggerGen(opt =>
            {
                //遍歷出所有的版本，作文檔信息展現
                typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
                {
                    opt.SwaggerDoc(version, new Info
                    {
                        // {ApiName} 定義成全局變量，方便修改
                        Version = version,
                        Title = $"{ApiName} 接口文檔",
                        Description = $"{ApiName} HTTP API " + version,
                        TermsOfService = "None",
                        Contact = new Contact
                        {
                            Name = "糯米粥",
                            Email = "nsky@cnblogs.com",
                            Url = "http://www.cnblogs.com/nsky"
                        }
                    });
                    // 按相對路徑排序，
                    opt.OrderActionsBy(o => o.RelativePath);

                    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                    opt.IncludeXmlComments(xmlPath, true);
                });

使用中間件:

//容許中間件做爲JSON端點爲生成的Swagger提供服務。
            app.UseSwagger();

            //配置swaggerui信息
            app.UseSwaggerUI(options =>
            {
                #region 單個版本控制
                //options.SwaggerEndpoint("/swagger/v1/swagger.json", "Api_v1");
                //s.RoutePrefix = string.Empty; 
                #endregion

                #region 多版本控制

                typeof(ApiVersions).GetEnumNames().OrderByDescending(e => e).ToList().ForEach(version =>
                {
                    options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{ApiName} {version}");
                });

                //foreach (var description in provider.ApiVersionDescriptions)
                //{
                //    options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
                //}
                #endregion
            });