您的位置:首页 > 编程语言 > ASP

AspnetCore WebApi使用Swagger简单入门

2019-03-23 12:17 876 查看

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

 

内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签: 
相关文章推荐