AspnetCore WebApi使用Swagger简单入门

微软官网入门：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
            });

 配置XML注释，右键属性，生成界面：

但如果有的方法没有xml注释，则会由1591警告信息

也可以在属性界面设置:

 一起准备完成，就是在Api代码写逻辑了，为了区分v1和v2的不同

 

 可以看到我上面用了CustomRoute自定义类，待会讲，参考网上的做法

运行项目，有2个版本的切换

路径是这样的：

 如果不想输入swagger，可以修改路由，把前缀RoutePrefix 清空，即可

 

可以看到，values不属于任何一个版本，所以，v1和v2都包含了。算是公共的api

 

现在测试下：

 github：https://github.com/byniqing/AspNetCore-Swagger