java开发,根据代码自动生成api接口文档工具,支持RESTful风格,今天我们来学一下api-doc的生成

作者:互联网编程。 欢迎投稿,一起交流技术

https://www.jianshu.com/u/4ea0af17fd67

预览

在线预览地址

http://lovepeng.gitee.io/apidoc

开发原理

这个工具是一个典型的前后端分离开发的项目,想了解前后端分离开发的同学也可以下载本项目学习。

项目后端使用java代码,前端使用angular开发。Java开发时,使用注解把文档相关信息标注在类的方法上,通过工具自动扫描代码的注解,生成json数据,发给前端,前端angular解析生成页面

本项目自带一个spring-boot框架为基础的demo(这里使用spring-boot做演示的demo仅仅是为了方便,本质上只要是java写的项目都可以用该工具),前端用angular做了一个比较漂亮的界面(最终前端界面都编译成了html,如果你前端不熟悉,可以跳过,不用管他),这里使用angular开发仅仅是我比较喜欢,你可以用任何你喜欢的的前端框架或者仅仅使用html写一个漂亮的界面就可以。

后端项目开源地址:https://github.com/liepeng328/api-doc

前端开源地址:https://github.com/liepeng328/api-doc-angular

快速启动

当成一个工具类用就可以了,下载本项目,拷贝包com.apidoc下的代码到你的系统,

然后拷贝前端html页面,在static.apidoc文件下,到你的资源文件下。即可使用

使用时,后台提供两个接口,目录文档接口和某个功能的详细接口

//生成目录接口
ApiDoc apiDoc = new GeneratorApiDoc()
.setInfo(//设置文档基本信息
new ApiDocInfo()
.setTitle("某莫系统后台管理文档")
.setVersion("1.0")
.setDescription("") )
.generator(packageName);//指定生成哪个包下controller的文档
System.err.println(JsonUtil.toString(detail)); //详细功能接口
ApiDocAction detail = new GeneratorApiDoc()
//设置数据库连接信息,可忽略
.setDriver(driver)
.setUrl(url)
.setUserName(userName)
.setPassword(password)
.setDataBaseName(dataBaseName)
.getApiOfMethod(methodUUID);
System.err.println(JsonUtil.toString(detail));

一个详细的例子

一个详细例子如下代码,这里是springboot/springmvc的controller示例(展示两个文档,前端接口和后台接口)参考代码这个类 UserController.java

注解详细介绍

共有6个注解,标注出整个文档信息(我为什么讲那么详细,那么啰嗦,而且我没有把这个项目打成jar包直接给别人使用,就是因为文档生成最大可能是需要特殊定制,确保你拿到该代码可以个性化定制功能,随意修改)。

  • Api 标注文档的功能模块
  • ApiAction 标注一个功能
  • ApiReqAparams 请求参数
  • ApiResqAparams 响应参数
  • ApiParam 参数,用以组成请求参数和响应参数
  • Table 用以标注实体类(比如bean)和数据库表的关系,自动从数据库读取相关信息,不用写大量的 ApiReqAparams和ApiResqAparams

详细介绍如下

Api:写在类上,表明一个功能模块。

属性:

  • name 模块名称
  • mapping url映射

ApiAction: 写在方法上,表明一个功能点

属性:

  • name 方法的功能名称
  • mapping url映射
  • description 描述
  • method 请求方式(get,post,put,delete)

ApiReqParams: 请求参数

属性:

  • type:参数类型
  • header 在请求头
  • url 在url后拼接
  • form 表单数据
  • json json格式
  • ApiParam :参数列表
  • value : class类,增加该类可自动读取数据库信息,避免写多个属性
  • remove: 配合value使用,去除class类中无用的属性,比如id
  • dataType: 数据类型(字符串string,数字number,文件file,日期date,对象object,数组array,布尔类型boolean)
  • descrption:描述
  • defaultValue: 默认值
  • required:是否必须
  • object:从属于哪个对象(因为请求参数或者响应参数可能是对象中嵌套对象的,这里为了更好的表示这种层级关系,增加两个属性,object和belongTo,构建一个树结构,表示对象之间无限、互相嵌套)
  • belognTo : 对应object 默认值为"0",字符串0

ApiRespParams: 响应参数

属性:

  • ApiParam: 该参数等同于请求参数中的ApiParam,参考如上描述

下载本项目并运行

配置jdk8以上版本,下载代码,运行ApidocApplication类main方法即可。

然后访问地址 http://localhost:8080/index.html

感谢列表

该项目为maven项目,引用工具请查看 pom.xml

感谢 spring-boot

Api文档自动生成工具的更多相关文章

  1. springboot成神之——swagger文档自动生成工具

    本文讲解如何在spring-boot中使用swagger文档自动生成工具 目录结构 说明 依赖 SwaggerConfig 开启api界面 JSR 303注释信息 Swagger核心注释 User T ...

  2. API文档自动生成,Swagger的配置

    ASP.NET的部署方式 第一步:引用程序集 打开NuGet程序包管理器,搜索Swagger,安装第一个,注意画圈的地方, 已经包含主程序和UI了,安装完成后会在根目录App_Start文件夹下生成S ...

  3. 使用swagger实现在线api文档自动生成 在线测试api接口

    使用vs nuget包管理工具搜索Swashbuckle 然后安装便可 注释依赖于vs生成的xml注释文件

  4. Word 2010文档自动生成目录和某页插入页码

    一.Word 2010文档自动生成目录 关于Word文档自动生成目录一直是我身边同学们最为难的地方,尤其是毕业论文,经常因为目录问题,被要求修改,而且每次修改完正文后,目录的内容和页码可能都会发生变化 ...

  5. VS文档自动生成

    VS2008文档自动生成 (发现,Sandcastle主要是用于C#项目.里面的注释都是XML格式的.不太适合VC的.最终还是得用Doxygen) 一.Sandcastle简介: Sandcastle ...

  6. 基于 React 开发了一个 Markdown 文档站点生成工具

    Create React Doc 是一个使用 React 的 markdown 文档站点生成工具.就像 create-react-app 一样,开发者可以使用 Create React Doc 来开发 ...

  7. django接口文档自动生成

    django-rest_framework接口文档自动生成 只针对用到序列化和返序列化 一般还是用第三方yipi 一.安装依赖 pip3 install coreapi 二.设置 setting.py ...

  8. API的文档自动生成——基于CDIF的SOA基本能力

    当前,作为大部分移动app和云服务后台之间的标准连接方式,REST API已经得到了绝大部分开发者的认可和广泛的应用.近年来,在新兴API经济模式逐渐兴起,许多厂商纷纷将自己的后台业务能力作为REST ...

  9. swagger:API在线文档自动生成框架

    传统的API从开发测试开始我们经常借用类似Postman.fiddle等等去做接口测试等等工具:Swagger 为API的在线测试.在线文档提供了一个新的简便的解决方案: NET 使用Swagger ...

  10. sphinx:python项目文档自动生成

    Sphinx: 发音: DJ音标发音: [sfiŋks] KK音标发音: [sfɪŋks] 单词本身释义: an ancient imaginary creature with a lion's bo ...

随机推荐

  1. 通过top命令发现plymouthd进程cpu负载达到近100% 解决办法

    最近几天一直遇到服务器cpu100%, 通过top命令发现plymouthd进程cpu负载达到近100% 解决方法:打开 /boot/grub/menu.lst , 去掉 “rhgb quiet”这两 ...

  2. js全局变量和局部变量

    <script> var i = 'yuanjianhang'; function myloveName() { alert(i); var i = 'guanxi'; } myloveN ...

  3. 解决iphone横屏时字体变大问题或者内容大小不一样等

    在样式表中增加: @media screen and (max-device-width: 320px){body{-webkit-text-size-adjust:none}} @media scr ...

  4. [PR &amp; ML 1] [Introduction] Informal Basic Concepts

    最近还没更完OpenCV又开了新坑,谁教machine learning处在紧急又重要的地位呢.更新的内容总结自Pattern Recognition and Machine Learning by ...

  5. Robot Framework学习路线

    0. 官方网站  http://robotframework.org/ 所有资料都来自这里,从这里找到必要的链接,从而深入其中的细节. 1.  Quick Start Guide https://co ...

  6. Mahout机器学习平台之聚类算法具体剖析(含实例分析)

    第一部分: 学习Mahout必需要知道的资料查找技能: 学会查官方帮助文档: 解压用于安装文件(mahout-distribution-0.6.tar.gz),找到例如以下位置.我将该文件解压到win ...

  7. 深入windows的关机消息截获-从XP到Win7的变化

    之前写了一个软件用于实验室的打卡提醒,其中一个重要的功能是在关机之前提醒当天晚上是否已经打卡.之前我是在WM_ENDSESSION中弹出一个模态对话框来提醒,在XP中基本工作正常,在Win7中大多数时 ...

  8. Redis内存模型(2):存储细节

    1. 概述 先看一下执行set hellow world时,所涉及的数据模型: (1)dictEntry:Redis是Key-Value数据库,因此对每个键值对都会有一个dictEntry,里面存储了 ...

  9. springdata 动态查询之排序

  10. js对象拷贝遇到的坑

    问题:通过拷贝赋值后,所有的对象的name居然都是C test(){ let person = [{'name':'danny'}] let names = ['A','B','C'] let tem ...