热门标签 | HotTags
当前位置:  开发笔记 > 编程语言 > 正文

ApiDoc一键生成注释

本文来自网易云社区。 作者:盛国存 背景我们日常在使用ApiDoc维护管理api文档,

本文来自网易云社区。

 

作者:盛国存

 

背景

我们日常在使用ApiDoc维护管理api文档,提高了api文档的整体维护性。但在老旧接口中,补充接口注解无疑是一次繁重的体力劳动。仔细查看,大多数接口的格式 其实是相似的,那么,是否可以将体力活做的技术一些?

答案是sure,只需要三步。分析log,构建接口数据,生成APIDoc。

 

过程阐述

下面以个人开发机器下的某个测试接口为例,阐述整个过程:

在实际的业务中可能存在这样的日志(前提是所有的业务日志都是通过同一套标准进行输出的)

重点看红框标注的部分。依次为,日志等级、logId、uri、arrRequest/action tpl data。仔细分析,我们会发现,TRACE模式即为请求,包含所有请求信息。DEBUG模式即为响应,包含所有响应信息。具体数据结构不做赘述。

以此为例,根据日志模式、logId、uri、arrRequest、tpl data 等信息可以构建标准的接口请求&返回信息。 

需要注意的是:

    1、单个日志中可能会存在日志的多个请求,所以要对分析后的日志做数据过滤; 

    2、如果接口返回数据中存在list,要对list做单一化处理(否则后续的生成的apidoc会存在大量重复字段); 

    3、日志读取尽量使用yield(要不大文件会扛不住的);

处理逻辑就不描述了,so easy。

那么添加一个新的apidoc的步骤现在变为:

    a、从log.dt解析接口的请求&返回数据;

    b、提取uri、method、requestparam、retData等字段; 

    c、根据接口uri每个接口只留取一个请求实例; 

    d、遍历接口返回数据的结构,list数组中只留取一个item实例; 

    e、根据apidoc的格式拼装数据,按照uri生成独立文件; 

    f、剪贴至action,并完成字段注释等操作;

其中a-e的操作 可以概述为 打开浏览器器(1s)→刷业务页面(10s)→执行脚本(1s)→复制粘贴(1s)→补充字段注释信息(xxxs)

只需要一个简单的命令

ApiDoc就写好了

再执行一下 apidoc -i xxxx -o xxxx 就大功告成了

总结

现实开发的过程中,存在着很多重复琐碎的事情,比如维护繁琐的文档,每更新一次代码都需要执行一次apidoc命令,有时候会经常忘记,我们可以搞一个crontab检测文件夹是否有过改动,有的话就自动执行一次命令,一年可以省下不少时间哩……^_^,日常还有很多类似的事,可以开发一些小工具将偷懒发挥到极致。

 

 

网易云免费体验馆,0成本体验20+款云产品!

 

更多网易研发、产品、运营经验分享请访问网易云社区。

 

 

 

相关文章:【推荐】 四六级成绩查询,你的『验证码』刷出来了吗?【推荐】 在Android中使用Protocol Buffers(下篇)



推荐阅读
  • MySQL性能优化与调参指南【数据库管理】
    本文详细探讨了MySQL数据库的性能优化与参数调整技巧,旨在帮助数据库管理员和开发人员提升系统的运行效率。内容涵盖索引优化、查询优化、配置参数调整等方面,结合实际案例进行深入分析,提供实用的操作建议。此外,还介绍了常见的性能监控工具和方法,助力读者全面掌握MySQL性能优化的核心技能。 ... [详细]
  • 深入解析Tomcat:开发者的实用指南
    深入解析Tomcat:开发者的实用指南 ... [详细]
  • 深入解析Gradle中的Project核心组件
    在Gradle构建系统中,`Project` 是一个核心组件,扮演着至关重要的角色。通过使用 `./gradlew projects` 命令,可以清晰地列出当前项目结构中包含的所有子项目,这有助于开发者更好地理解和管理复杂的多模块项目。此外,`Project` 对象还提供了丰富的配置选项和生命周期管理功能,使得构建过程更加灵活高效。 ... [详细]
  • 本文深入解析了 Apache 配置文件 `httpd.conf` 和 `.htaccess` 的优化方法,探讨了如何通过合理配置提升服务器性能和安全性。文章详细介绍了这两个文件的关键参数及其作用,并提供了实际应用中的最佳实践,帮助读者更好地理解和运用 Apache 配置。 ... [详细]
  • Spring Boot 实战(一):基础的CRUD操作详解
    在《Spring Boot 实战(一)》中,详细介绍了基础的CRUD操作,涵盖创建、读取、更新和删除等核心功能,适合初学者快速掌握Spring Boot框架的应用开发技巧。 ... [详细]
  • 结语 | 《探索二进制世界:软件安全与逆向分析》读书笔记:深入理解二进制代码的逆向工程方法
    结语 | 《探索二进制世界:软件安全与逆向分析》读书笔记:深入理解二进制代码的逆向工程方法 ... [详细]
  • HBase在金融大数据迁移中的应用与挑战
    随着最后一台设备的下线,标志着超过10PB的HBase数据迁移项目顺利完成。目前,新的集群已在新机房稳定运行超过两个月,监控数据显示,新集群的查询响应时间显著降低,系统稳定性大幅提升。此外,数据消费的波动也变得更加平滑,整体性能得到了显著优化。 ... [详细]
  • Django框架下的对象关系映射(ORM)详解
    在Django框架中,对象关系映射(ORM)技术是解决面向对象编程与关系型数据库之间不兼容问题的关键工具。通过将数据库表结构映射到Python类,ORM使得开发者能够以面向对象的方式操作数据库,从而简化了数据访问和管理的复杂性。这种技术不仅提高了代码的可读性和可维护性,还增强了应用程序的灵活性和扩展性。 ... [详细]
  • 技术日志:深入探讨Spark Streaming与Spark SQL的融合应用
    技术日志:深入探讨Spark Streaming与Spark SQL的融合应用 ... [详细]
  • 在 Linux 系统中,`/proc` 目录实现了一种特殊的文件系统,称为 proc 文件系统。与传统的文件系统不同,proc 文件系统主要用于提供内核和进程信息的动态视图,通过文件和目录的形式呈现。这些信息包括系统状态、进程细节以及各种内核参数,为系统管理员和开发者提供了强大的诊断和调试工具。此外,proc 文件系统还支持实时读取和修改某些内核参数,增强了系统的灵活性和可配置性。 ... [详细]
  • 深入解析零拷贝技术(Zerocopy)及其应用优势
    零拷贝技术(Zero-copy)是Netty框架中的一个关键特性,其核心在于减少数据在操作系统内核与用户空间之间的传输次数。通过避免不必要的内存复制操作,零拷贝显著提高了数据传输的效率和性能。本文将深入探讨零拷贝的工作原理及其在实际应用中的优势,包括降低CPU负载、减少内存带宽消耗以及提高系统吞吐量等方面。 ... [详细]
  • 深入解析:RKHunter与AIDE在入侵检测中的应用与优势
    本文深入探讨了RKHunter与AIDE在入侵检测领域的应用及其独特优势。通过对比分析,详细阐述了这两种工具在系统完整性验证、恶意软件检测及日志文件监控等方面的技术特点和实际效果,为安全管理人员提供了有效的防护策略建议。 ... [详细]
  • 本文深入探讨了IO复用技术的原理与实现,重点分析了其在解决C10K问题中的关键作用。IO复用技术允许单个进程同时管理多个IO对象,如文件、套接字和管道等,通过系统调用如`select`、`poll`和`epoll`,高效地处理大量并发连接。文章详细介绍了这些技术的工作机制,并结合实际案例,展示了它们在高并发场景下的应用效果。 ... [详细]
  • 本文将介绍一种扩展的ASP.NET MVC三层架构框架,并通过使用StructureMap实现依赖注入,以降低代码间的耦合度。该方法不仅能够提高代码的可维护性和可测试性,还能增强系统的灵活性和扩展性。通过具体实践案例,详细阐述了如何在实际开发中有效应用这一技术。 ... [详细]
  • 本文深入探讨了NDK与JNI技术在实际项目中的应用及其学习路径。通过分析工程目录结构和关键代码示例,详细介绍了如何在Android开发中高效利用NDK和JNI,实现高性能计算和跨平台功能。同时,文章还提供了从基础概念到高级实践的系统学习指南,帮助开发者快速掌握这些关键技术。 ... [详细]
author-avatar
拍友2702938227
这个家伙很懒,什么也没留下!
PHP1.CN | 中国最专业的PHP中文社区 | DevBox开发工具箱 | json解析格式化 |PHP资讯 | PHP教程 | 数据库技术 | 服务器技术 | 前端开发技术 | PHP框架 | 开发工具 | 在线工具
Copyright © 1998 - 2020 PHP1.CN. All Rights Reserved | 京公网安备 11010802041100号 | 京ICP备19059560号-4 | PHP1.CN 第一PHP社区 版权所有