码迷,mamicode.com
首页 > Windows程序 > 详细

AspnetCore WebApi使用Swagger简单入门

时间:2019-03-23 13:01:43      阅读:240      评论:0      收藏:0      [点我收藏+]

标签:href   入门   可视化   风格   log   custom   右键   reg   cut   

微软官网入门: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

 

AspnetCore WebApi使用Swagger简单入门

标签:href   入门   可视化   风格   log   custom   右键   reg   cut   

原文地址:https://www.cnblogs.com/nsky/p/10583343.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!