借助中间件自动化文档
编写这个中间件的理由:
- 常见的自动化文档库,比如swagger,只能依赖于XML注释.这种文档,生成的数据样本单一,而且与代码脱节改起来非常讨厌.
- 为了装逼.
使用方法
public class Startup
{
public void Configuration(IAppBuilder app)
{
var config = new HttpConfiguration();
var container = new CompositionContainer(new ApplicationCatalog(), true);
config.Services.Replace(typeof(IContentNegotiator), new CustomJsonContentNegotiator());
config.Services.Replace(typeof(IHttpControllerActivator), new CustomControllerActivator(container));//MEF,IOC容器注入
config.MapHttpAttributeRoutes();
app.UseCors(CorsOptions.AllowAll);//使用Cors开启跨域,这里为了方便,直接AllowAll了
app.UseWebApi(config);
app.Use<WebApiDocumenting.WebApiDocumenting>(config);//看这里,Use一个中间件即可,是不是很简单?对业务代码,几乎0侵染性
}
}
//然后就会生出一个json,这里我用VueJs做了界面,基于当时Vue组件还不是很多,所以弄的一般般(主要没有做前端路由),就不放出来献丑了.
//你也可以在DTO中的属性,DTO的类名,Action中添加注解,会生出对应包含注释的json.
[Description("创建新闻")]
public class CreateNewsInfo
{
public string Title { get; set; }
[Name]//目前框架提供的注解不是很多,主要是,要提供非常完美的数据样本,必须依托于巨大数据库.懒得弄
public string Introduction { get; set; }
[Description("新闻类型")]//目前框架提供的注解不是很多,主要是,要提供非常完美的数据样本,必须依托于巨大数据库.懒得弄
public int Type { get; set; }
public bool IsHidden { get; set; }
public bool IsTop { get; set; }
public string Icon { get; set; }
public string Content { get; set; }
}
文档中间件项目介绍
承接上一章的内容,我现在要写一个中间件,输出所有的ApiInfo.怎么做?
- 我的中间件里默认传入的数据是OwinContext(由Adapter转化成了HttpContxt而来),
我要知道程序集相关的内容,就必须从HttpConfiguration反射出来
所以中间件的构造注入一个HttpConfiguration
public class WebApiDocumenting : OwinMiddleware
{
private readonly HttpConfiguration _configuration;
public WebApiDocumenting(OwinMiddleware next, HttpConfiguration configuration)
: base(next)
{
_configuration = configuration;
}
public override async Task Invoke(IOwinContext context)
{
//这里根据_configuration获取所有Api信息
if (!IsDocumentRequest(context))
{
await Next.Invoke(context);
return;
}
//传入HttpConfiguration构造我需要的数据,具体详情请见代码.这里仅介绍中间件的使用
var siteInfoBuilder = new SiteInfoBuilder(_configuration);
var siteInfo = siteInfoBuilder.Build();
var json = JsonConvert.SerializeObject(siteInfo, new JsonSerializerSettings()
{
Formatting = Formatting.Indented,
ContractResolver = new CamelCasePropertyNamesContractResolver()
});
context.Response.Write(json);
context.Response.ContentType = "application/json;charset=utf-8";
}
private static bool IsDocumentRequest(IOwinContext context)
{
return string.Compare(context.Request.Path.Value, "/$document", StringComparison.OrdinalIgnoreCase) == 0;
}
}
根据HttpConfiguration反射出所有的信息,具体请看源码
修改Json.net配置,让其生成可以注释的json,具体请看源码
源码地址:https://github.com/songtinHuang/Songtin.AutoDocument
啊,折腾好久,终于在VS2013上装好github插件了,下一步就是买github外套假装自己是geeker了.
呵呵.
