前言
之前写Java都是自动生成接口文档在线调式的,现在写C#只能每个接口复制粘贴到接口测试工具上,,,很麻烦。
慎重声明:代码很大部分是复制别个的,有些找不到来源了。
创建项目
我用的是Rider,比较顺手,但是Rider无法创建白板Api 项目(需要另外的配置,麻烦),只能创建MVC项目很杂,看的不爽,所以用的是VS2017。
项目创建
选择API项目
最开始我选择是Web API,但还是在MVC项目结构的基础上创建的,很乱,不喜欢。后面偶然百度才知道这样创建。
依赖安装
第一个应该是依赖的依赖包,自动下载的。
配置修改
参考:C# (WebApi)整合 Swagger_c# swagger-CSDN博客
添加一个类
在APP_Start文件夹下添加类SwaggerCacheProvider.cs 名字不重要,引用的时候改改就行。
这个类不做修改,偶也是复制过来的。
/// <summary>
/// swagger 显示控制器的描述
/// </summary>
public class SwaggerCacheProvider : ISwaggerProvider
{
private readonly ISwaggerProvider _swaggerProvider;
private static ConcurrentDictionary<string, SwaggerDocument> _cache = new ConcurrentDictionary<string, SwaggerDocument>();
private readonly string _xmlPath;
/// <summary>
///
/// </summary>
/// <param name="swaggerProvider"></param>
/// <param name="xmlpath">xml文档路径</param>
public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xmlpath)
{
_swaggerProvider = swaggerProvider;
_xmlPath = xmlpath;
}
public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
{
var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
//只读取一次
if (!_cache.TryGetValue(cacheKey, out SwaggerDocument srcDoc))
{
srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);
srcDoc.vendorExtensions = new Dictionary<string, object>
{
{ "ControllerDesc", GetControllerDesc() }
};
_cache.TryAdd(cacheKey, srcDoc);
}
return srcDoc;
}
/// <summary>
/// 从API文档中读取控制器描述
/// </summary>
/// <returns>所有控制器描述</returns>
public ConcurrentDictionary<string, string> GetControllerDesc()
{
ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();
if (File.Exists(_xmlPath))
{
XmlDocument xmldoc = new XmlDocument();
xmldoc.Load(_xmlPath);
string[] arrPath;
int cCount = "Controller".Length;
foreach (XmlNode node in xmldoc.SelectNodes("//member"))
{
string type = node.Attributes["name"].Value;
if (type.StartsWith("T:"))
{
arrPath = type.Split('.');
string controllerName = arrPath[arrPath.Length - 1];
if (controllerName.EndsWith("Controller")) //控制器
{
//获取控制器注释
XmlNode summaryNode = node.SelectSingleNode("summary");
string key = controllerName.Remove(controllerName.Length - cCount, cCount);
if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))
{
controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());
}
}
}
}
}
return controllerDescDict;
}
}
修改项目属性
右键项目点击属性
修改SwaggerConfig文件
依赖安装完成之后再APP_Start文件夹下会生成SwaggerConfig文件,直接改成以下配置。
好像还会生成一个 什么Net.cs文件,但是没有被引用 我就删除了
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "WebApplication5");
//添加下述代码
//注意这里的xml文件名要改成你自己的!!!!
var xmlFile = string.Format("{0}/bin/WebApplication5.xml",
System.AppDomain.CurrentDomain.BaseDirectory);
if (System.IO.File.Exists(xmlFile))
{
c.IncludeXmlComments(xmlFile);
}
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, xmlFile));
})
.EnableSwaggerUi(b =>
{
//这个地方应该是为了添加注释用的,但是我百度好多地方都是引用自己生成一个js文件,偶然发现SwaggerUI文件夹下(安装依赖生成的文件夹)的swagger-ui.js和自己复制过来的文件一样,我就直接引用这个文件了
b.InjectJavaScript(Assembly.GetExecutingAssembly(), "WebApplication5.SwaggerUI.swagger-ui.js");
});
}
}
最终目录
总结:安装依赖包Swashbuckle和Swagger.Net.UI后 添加一个SwaggerCacheProvider.cs文件,修改SwaggerConfig文件,引用一个js文件,引用文件前修改项目属性。
看看效果
写一个测试接口
public class UsetTController: ApiController
{
/// <summary>
/// 更新订单信息
/// </summary>
/// <param name="input"></param>
/// <returns></returns>
[HttpPost, Route("order/UpdateOrder")]
public string UpdateOrder(string input)
{
return JsonConvert.SerializeObject(new { code=200,msg="123",data = new List<string> { "1","1","1"} }); ;
}
/// <summary>
/// 测试能否显示 这个就是接口注释
/// </summary>
/// <param name="input">参数1 这个就是参数注释</param>
/// <param name="a">参数a</param>
/// <param name="b">参数b</param>
/// <param name="c">参数c</param>
/// <returns></returns>
[HttpPost, Route("order/GetTest")]
public BaseResponse<object> GetTest(string input,string a,string b,string c)
{
return R.OkK<object>("sjaidjioasjdjasdja");
}
}
访问 http://localhost:52787/swagger/ui/index