AspnetCore WebApi使用Swagger简单入门

2019-03-23 12:17 糯米粥阅读(578) 评论(0) 编辑收藏举报

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

Swagger是一个支持Rest Api的，用于可视化。也就是说你的WebApi必须遵循RestApi架构风格，否则是无法生成Api文档的

依赖包：

Swashbuckle.Aspnetcore：用于生成Swagger文档

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

因为接口会不断的升级，迭代，所以必然会有版本控制，这样新的版本不会影响就的版本

所以，我这里一开始就会搭建一个版本控制

创建Api项目，默认会有Value控制器，然后分别添加v1和v2文件夹，创建ManagerController

添加版本控制类，添加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分组，就是说明该控制器是那个版本组

创建用于测试的实体类：

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
            });