我的设计接口总结以及生成帮助文档

前言:在工作发现接口至关重要,特别需要把接口的注释写清楚,能调用的同事知道这个接口是干嘛用的,要传递什么参数等,在这里我做了一个简单的接口并生成帮助帮助,供大家相互学习,有好的可以提出来我继续改进。

第一步:建立一个用户接口(明确这个接口的作用)

按照Add,Delete,Update,Get模式来定义接口的方法(我个人觉得尽可能的重载)

第二步:方法中写出尽可能详尽的注释

按照方法实现的功能,参数意思,异常,备注,返回值等来写

第三步:接口中如果出现参数为类型的时候千万不要用1,2这样的数值代替尽可能用枚举

为什么用枚举:因为在实际项目中可能做到最后的时候自己都不知道1代表什么2代表什么,通过枚举就能解决这些问题,而且枚举扩展性也很好

现在我们看一下我写的接口

 1 /// <summary>
 2     /// 关于用户信息的操作
 3     /// </summary>
 4     public interface IUser
 5     {
 6         /// <summary>
 7         /// 添加用户信息
 8         /// </summary>
 9         /// <param name="userInfo">用户实体</param>
10         /// <exception cref="ArgumentNullException">userInfo为null</exception>
11         /// <exception cref="ArgumentException">userInfo.Id为空字符串</exception>
12         /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception>
13         /// <exception cref="ArgumentException">userInfo.PassWord为空字符串</exception>
14         /// <exception cref="Exception">其他未知异常</exception>
15         /// <returns>true:添加成功 false:添加失败</returns>
16         bool Add(UserInfo userInfo);
17
18         /// <summary>
19         /// 根据用户名删除用户
20         /// </summary>
21         /// <param name="userName">用户名</param>
22         /// <exception cref="ArgumentException">userName为空字符串</exception>
23         /// <exception cref="Exception">其他未知异常</exception>
24         /// <returns>true:删除成功 false:删除失败</returns>
25         bool Delete(string userName);
26
27         /// <summary>
28         /// 根据用户名批量删除用户
29         /// </summary>
30         /// <param name="userNames">用户名(可以单个也可以多个)</param>
31         /// <exception cref="ArgumentNullException">userNames为null</exception>
32         /// <exception cref="ArgumentException">userNames不是有效参数</exception>
33         /// <exception cref="Exception">其他未知异常</exception>
34         ///<remarks>加入事物,如果其中一条未能删除成功,所有数据进行回滚</remarks>
35         /// <returns>true:删除成功 false:删除失败</returns>
36         bool Delete(IList<string> userNames);
37
38         /// <summary>
39         /// 更新用户信息
40         /// </summary>
41         /// <exception cref="ArgumentNullException">userInfo为null</exception>
42         /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception>
43         /// <exception cref="Exception">其他未知异常</exception>
44         /// <returns>true:更新成功 false:更新失败</returns>
45         bool Update(UserInfo userInfo);
46
47         /// <summary>
48         /// 根据用户名获取用户信息
49         /// </summary>
50         /// <exception cref="ArgumentException">userName为空字符串</exception>
51         /// <exception cref="Exception">其他未知异常</exception>
52         /// <returns>返回一条用户信息可为null</returns>
53         UserInfo Get(string userName);
54
55         /// <summary>
56         /// 根据用户名获取批量用户信息
57         /// </summary>
58         /// <param name="userNames">用户名(可以单个也可以多个)</param>
59         /// <exception cref="ArgumentNullException">userNames为null</exception>
60         /// <exception cref="ArgumentException">userNames不是有效参数</exception>
61         /// <exception cref="Exception">其他未知异常</exception>
62         /// <remarks>如果返回结果为空则返回一条没有任何用户的结果集</remarks>
63         /// <returns>获取用户集</returns>
64         IList<UserInfo> Get(IList<string> userNames);
65
66         /// <summary>
67         /// 根据职称类型获取用户信息
68         /// </summary>
69         /// <param name="professional"></param>
70         /// <exception cref="ArgumentOutOfRangeException">professional枚举不在范围内</exception>
71         /// <exception cref="Exception">其他未知异常</exception>
72         /// <returns>获取用户集</returns>
73         IList<UserInfo> Get(UserEnum.ProfessionalType professional);
74     }

用户接口

第四步:实现这个接口

因为项目一上线错误出现以后就很难发现,所以我们一定要加入日志系统,所以在项目中我加入了抛异常,然后通过日志就知道问题出现在哪里(没有实现功能)

  1     /// <summary>
  2     /// 实现用户相关操作
  3     /// </summary>
  4     public class User:IUser {
  5
  6         public bool Add(UserInfo userInfo)
  7         {
  8             try
  9             {
 10                 if (userInfo == null)
 11                     throw new ArgumentNullException("userInfo");
 12                 if (string.IsNullOrEmpty(userInfo.Id))
 13                     throw new ArgumentException("userInfo.Id无效");
 14                 if (string.IsNullOrEmpty(userInfo.UserName))
 15                     throw new ArgumentException("userInfo.UserName无效");
 16                 if (string.IsNullOrEmpty(userInfo.PassWord))
 17                     throw new ArgumentException("userInfo.PassWord无效");
 18                 return false;
 19             }
 20             catch
 21             {
 22                 throw new Exception("其他未知异常");
 23             }
 24         }
 25
 26         public bool Delete(string userName)
 27         {
 28             try
 29             {
 30                 if (string.IsNullOrEmpty(userName))
 31                     throw new ArgumentException("UserName无效");
 32                 return false;
 33             }
 34             catch
 35             {
 36                 throw new Exception("其他未知异常");
 37             }
 38         }
 39
 40         public bool Delete(IList<string> userNames)
 41         {
 42             try
 43             {
 44                 if (userNames == null)
 45                     throw new ArgumentNullException("userNames");
 46                 if (!userNames.Any())
 47                     throw new ArgumentException("userNames无效");
 48                 return false;
 49             }
 50             catch
 51             {
 52                 throw new Exception("其他未知异常");
 53             }
 54         }
 55
 56         public bool Update(UserInfo userInfo)
 57         {
 58             try
 59             {
 60                 if (userInfo == null)
 61                     throw new ArgumentNullException("userInfo");
 62                 if (string.IsNullOrEmpty(userInfo.UserName))
 63                     throw new ArgumentException("userInfo.UserName无效");
 64                 return false;
 65             }
 66             catch
 67             {
 68                 throw new Exception("其他未知异常");
 69             }
 70
 71         }
 72
 73         public UserInfo Get(string userName)
 74         {
 75             try
 76             {
 77                 if (string.IsNullOrEmpty(userName))
 78                     throw new ArgumentException("UserName无效");
 79                 return null;
 80             }
 81             catch {
 82                 throw new Exception("其他未知异常");
 83             }
 84         }
 85
 86         public IList<UserInfo> Get(IList<string> userNames)
 87         {
 88             try
 89             {
 90                 if (userNames == null)
 91                     throw new ArgumentNullException("userNames");
 92                 if (!userNames.Any())
 93                     throw new ArgumentException("userNames无效");
 94                 return null;
 95             }
 96             catch {
 97                 throw new Exception("其他未知异常");
 98             }
 99
100         }
101
102         public IList<UserInfo> Get(UserEnum.ProfessionalType professional)
103         {
104             try
105             {
106                 if (professional >= (UserEnum.ProfessionalType)4)
107                     throw new ArgumentOutOfRangeException("professional");
108                 return null;
109             }
110             catch {
111                 throw new Exception("其他未知异常");
112             }
113
114         }
115     }

实现接口

第五步:点击项目属性,找到生成勾选xml文档文件如下图

第六步:下载一个Sandcastle Help File Builder 然后安装,安装成功以后,找到Sandcastle Help File Builder新建一个项目如下图

第七步:找到生成的dll和xml文件然后导入如下图

第八步:点击生成按钮就可以生成一篇帮助文档了

生成帮助文档的效果

以上就是整个效果,大家有好的欢迎相互讨论。

时间: 2024-12-20 16:29:32

我的设计接口总结以及生成帮助文档的相关文章

SpringBoot+rest接口+swagger2生成API文档+validator+mybatis+aop+国际化

代码地址:JillWen_SpringBootDemo mybatis 1. 添加依赖: <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>${mybatis.version}</version> </dependency> &

vs2010代码注释自动生成api文档

最近做了一些接口,提供其他人调用,要写个api文档,可是我想代码注释已经写了说明,能不能直接把代码注释生成api?于是找到以下方法 环境:vs2010 先下载安装Sandcastle 和Sandcastle Help File Builder 下载地址 http://sandcastle.codeplex.com/ http://shfb.codeplex.com/ 其中Sandcastle Help File Builder安装较复杂,安装红框内的即可 安装完成后,然后让要使用的项目输出xml

C#简单实现动态数据生成Word文档并保存

今天正好有人问我,怎么生成一个报表式的Word文档. 就是文字的样式和位置相对固定不变,只是里面的内容从数据中读取. 我觉得类似这种的一般用第三方报表来做比较简便.但既然要求了Word,只好硬着头皮来. 网上的方法大多数都是从一个GridView或表中获得数据后向Word中添加一个表格. (图1) 我们使用Word模板来实现,方法如下: 1.首先需要向工程中的“引用”加入Word类库的引用(图2).我是Office 2003.其他版本可能略有不同.在COM里面 (图2) 2.用Word设计一个模

webAPI 自动生成帮助文档

之前在项目中有用到webapi对外提供接口,发现在项目中有根据webapi的方法和注释自动生成帮助文档,还可以测试webapi方法,功能很是强大,现拿出来与大家分享一下. 先看一下生成的webapi文档. 1.下图展示的是生成帮助文档首页面,其中Values是controller,API下面的列表展示出请求的http方法(Get,POST等),请求的action,方法的描述. 2.点击红框内的链接,打开api方法的详情页面,如下图所示, 3.点击Test API打开如下页面 4.输入参数,点击S

使用PHP生成PDF文档

原文:使用PHP生成PDF文档 实际工作中,我们要使用PHP动态的创建PDF文档,目前有许多开源的PHP创建PDF的类库,今天我给大家来介绍一款优秀的PDF库,它就是TCPDF,TCPDF是一个用于快速生成PDF文件的PHP5函数包.TCPDF基于FPDF进行扩展和改进,增强了实用功能. 使用PHP生成PDF文档 实际工作中,我们要使用PHP动态的创建PDF文档,目前有许多开源的PHP创建PDF的类库,今天我给大家来介绍一款优秀的PDF库,它就是TCPDF,TCPDF是一个用于快速生成PDF文件

PHP读取注释生成api文档

总结就是,正则要用的好. 需要生成api的class文件: <?php class emailAction { /** * @method 发送邮件 * @url email/send?token=xxx * @http POST * @param token string [必填] 调用接口凭证 (post|get) * @param ema_type enum [必填] 发送速度:'普通','紧急','延时' * @param ema_from enum [必填] 来源:'B2C','主站'

注释生成Api文档

1.开发背景 最近一直在写dubbo接口,以前总是用word文档写接口描述然后发给别人.现在太多了,而且跟别人对接联调的人家急着用,根本没时间去写word文档.那就想想怎么用doc文档注释自动生成接口文档了.本来以前对这一块有点印象,但是并不熟悉,加上没有很强烈的要去使用的意图,所以一直没有弄.今天要感谢公司的大神,大家都叫他欧神,神一样的男人.让我用文档注释.然后就知道怎么弄了,以下是生成的流程. 2.生成方法 先说生成的方法吧,免得一开始将注释规范可能读者觉得比较繁琐,而且注释规范基本上大家

利用Java动态生成 PDF 文档

利用Java动态生成 PDF 文档,则需要开源的API.首先我们先想象需求,在企业应用中,客户会提出一些复杂的需求,比如会针对具体的业务,构建比较典型的具备文档性质的内容,一般会导出PDF进行存档.那么目前最佳的解决方案,你可能会想到 iText ,对没错... iText+(Velocity / Freemarker)可以实现.不过据我熟悉,iText本身提供的HTML解析器还是不够强大,许多HTML标签和属性无法识别,更悲催的是简单的CSS它不认识,排版调整样式会让你头大的.不要失望,接下来

asp.net webAPI 自动生成帮助文档并测试

之前在项目中有用到webapi对外提供接口,发现在项目中有根据webapi的方法和注释自动生成帮助文档,还可以测试webapi方法,功能很是强大,现拿出来与大家分享一下. 先看一下生成的webapi文档. 1.下图展示的是生成帮助文档首页面,其中Values是controller,API下面的列表展示出请求的http方法(Get,POST等),请求的action,方法的描述. 2.点击红框内的链接,打开api方法的详情页面,如下图所示, 3.点击Test API打开如下页面 4.输入参数,点击S