接口文档对于前后端分离是非常重要的一环,LinkCore当然也能自动生成文档.而且搭载的平台是POSTMAN
注意
LINKCORE已经支持到 NET5.0+ 本文章只使用NET3.0
LinkCore?
提前准备
- 参考路由设置新建一个 WebMain 的路由项目
- 引入 WebMain 根目录下的 LinkCore.Interface.dll
- 安装POSTMAN APP
这里用WebMain项目为例
XML文件输出配置
.csproj文件里增加输出配置
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
<OutputPath>....ReleaseWebLinkCoreplugins插件名称</OutputPath>
<DocumentationFile>....ReleaseWebLinkCoredoc插件名称.xml</DocumentationFile>
<NoWarn>1701;1702;1591</NoWarn>
</PropertyGroup>
1591警告推荐忽略,编译的时候没那么闹心 :)
Controller 接口生成
LinkCore生成文档的方法是通过注释来完成的 所以在接口控制器中我们对方法可以进行一定格式的注释达到文档标准输出的要求
一个简单的例子
/// <summary>
/// 用户相关接口
/// </summary>
class User : Router
{
/// <summary>
/// 一个例子
/// </summary>
/// <json>
/// <item name="_id" value="" type="String" required="1">编号</item>
/// <item name="Tag" value="" type="String[]">标签集合</item>
/// </json>
public void Index()
{
ResponseWriteBody("Success!!");
}
}
如果注释格式无误,编译后通过/POSTMAN:<PluginName>地址就是PostMan的导入地址了.当然
最终效果显示如下:
Class注释
# 添加了Class注释后才能输出文档
/// <summary>
/// 用户相关接口
/// </summary>
class User : Router
{
}
路由映射
/// <summary>
/// 用户相关接口
/// </summary>
/// <router>/V1/User</router>
class User : Router
{
}
JSON类型接口
# 这个例子说明了Request.Body.ContentType是application/json类型
# 暂时只支持这种类型,后续会考虑增加 x-www-form-urlencoded 类型
/// <summary>
/// 一个例子
/// </summary>
/// <json>
/// ...
/// </json>
Request 参数
/// <summary>
/// 一个例子
/// </summary>
/// <json>
# 参数名 name, 默认值 value, 参数类型 type
# required表示该字段必传
/// <item name="_id" value="" type="String" required="1">编号</item>
# 参数类型可以参考C#的支持类型,数组类型可以使用`[]`结尾
/// <item name="Tag" value="" type="String[]">标签集合</item>
/// </json>
引用Model
PluginName.UserModel
namespace PluginName
{
# 请注意isModel是必须加载Class的summary标签里的
/// <summary isModel="1">
/// 用户模型
/// </summary>
public class UserModel
{
/// <summary>
/// 用户名
/// </summary>
public string UserName { get; set; }
/// <summary>
/// 密码
/// </summary>
public string Password { get; set; }
}
}
引用的方法
/// <summary>
/// 应用模型接口
/// </summary>
/// <json>
# required可以限定必传的参数,多个属性可以用英文逗号隔开
# not 表示不想被引入的属性,多个属性可以用英文逗号隔开
/// <item model="PluginName.UserModel" required="UserName" not="Password"></item>
/// </json>
关于Mock
内置了 PostMan 的 Dynamic Variables
/// <summary>
/// 一个例子
/// </summary>
/// <json>
# value可以指定为 Dynamic Variables
/// <item name="UserName" value="$randomUserName" type="String">标签集合</item>
/// </json>
# 一个模型的属性mock默认值
/// <summary isModel="1">
/// 用户模型
/// </summary>
public class UserModel
{
/// <summary>
/// 用户名
/// </summary>
/// <mock>$randomJobTitle</mock>
public string UserName { get; set; }
/// <summary>
/// 密码
/// </summary>
/// <mock>$randomPassword</mock>
public string Password { get; set; }
}
结果创建变量
/// <summary>
/// 用户注册
/// </summary>
/// <json>
/// <item model="UserCentralModel.UserModel" required="UserName,Password"></item>
/// </json>
/*************************************************************
setvariable 使用 Response.Data 的结果来更新 userId 变量
*************************************************************/
/// <setvariable variable="userId" value="Data"></setvariable>
public void Register()
{
UserModel userModel = JSON.To<UserModel>(RequestReadBody());
userModel.SetIDB(Utiliy.db);
var userId = userModel.Add();
Dictionary<string, object> dict = new Dictionary<string, object>();
dict.Add("Code", "0000");
dict.Add("Data", userId);
ResponseWriteBody(JSON.Stringify(dict));
}
/// <summary>
/// 修改密码
/// </summary>
/// <json>
/*************************************************************
如果先调用过Register接口,POSTMAN会产生 userId 的变量可以被直接调用
*************************************************************/
/// <item name="_id" value="$userId" type="String">用户ID</item>
/// <item name="OldPassword" value="$randomPassword" type="String">原密码</item>
/// <item name="NewPassword" value="$randomPassword" type="String">新密码</item>
/// </json>
public void ChangePassword()
{
...
}
补充说明
接口生成之后，会根据该插件生成一份接口 => 名称的字典缓存可以通过如下方式获得。
ICache.Get(pluginName + "ApiDict");