HttpDoc零侵入的 RESTful API 文档框架
HttpDoc 是一个基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线阅览文档及测试界面框架。
JSON-Editor: httpdoc-ui TextArea: httpdoc-ui-v1
功能特性
-
基础功能无需为配合HttpDoc框架而多写一句代码,甚至连doc注释都不必写,即可拥有项目的API文档和测试界面。
-
遵循 RFC 2616 HTTP/1.1 规范,适配主流后台WEB框架。
-
拓展多个 Java Doc 注释标签,满足不同的文档阅览及在线测试需求。
-
一键生成SDK,支持多个平台,让前后台以及跨平台对接变得更简单。
-
WEB服务器无关,同时支持 Spring Boot 命令方式启动。
-
支持 Maven Gradle 或JAR包依赖。
环境依赖
JDK 1.7 +
集成步骤
Maven
-
引入依赖
<project> <!-- 设置 jitpack.io 仓库 --> <repositories> <repository> <id>jitpack.io</id> <url>https://www.jitpack.io</url> </repository> </repositories> <dependencies> <!-- 添加 HttpDoc 依赖 --> <dependency> <groupId>com.github.core-lib.httpdoc</groupId> <artifactId>httpdoc-spring-mvc</artifactId> <version>v1.5.3</version> </dependency> <!-- 添加JDK的tools.jar依赖用于解析源码注释,采用这种方式部署到Tomcat时需要往Tomcat的lib目录增加该tools.jar --> <dependency> <groupId>com.sun</groupId> <artifactId>tools</artifactId> <version>1.8</version> <scope>system</scope> <systemPath>${env.JAVA_HOME}/lib/tools.jar</systemPath> </dependency> <!-- 当然还有很多种方式来依赖tools.jar,例如上传到自己的私服或从别的仓库中依赖进来 --> </dependencies> </project>
-
配置插件
<!-- 由于框架基于源码注释解析来实现,所以保留源码是基础,如果只想要在线测试而没有文档阅览的需求,可不必添加该插件。--> <!-- 如果项目是多模块项目,需要被解析的源码类分散在多模块中,则其他模块也需要配置该插件,或在父项目的pom.xml中配置该插件。--> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-resources-plugin</artifactId> <version>3.1.0</version> <configuration> <encoding>UTF-8</encoding> </configuration> <executions> <execution> <id>copy-src</id> <phase>process-sources</phase> <goals> <goal>copy-resources</goal> </goals> <configuration> <outputDirectory>${project.build.directory}/classes</outputDirectory> <resources> <resource> <directory>${basedir}/src/main/java</directory> </resource> </resources> </configuration> </execution> </executions> </plugin>
-
配置参数
-
SpringMVC
<web-app> <servlet> <servlet-name>httpdoc</servlet-name> <servlet-class>io.httpdoc.web.HttpdocServletSupport</servlet-class> <init-param> <param-name>httpdoc</param-name> <param-value>项目名称</param-value> </init-param> <init-param> <param-name>version</param-name> <param-value>项目版本</param-value> </init-param> <init-param> <param-name>description</param-name> <param-value> <![CDATA[ 项目描述(可以内嵌HTML标签) ]]> </param-value> </init-param> <init-param> <param-name>dateFormat</param-name> <param-value>yyyy-MM-dd HH🇲🇲ss</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>httpdoc</servlet-name> <url-pattern>/httpdoc.json</url-pattern> </servlet-mapping> </web-app>
<mvc:resources mapping="/httpdoc-ui/**" location="classpath:/META-INF/resources/httpdoc-ui/"/>
-
spring-servlet.xml 中增加一个标签以允许浏览器访问HttpDoc的页面静态资源
-
web.xml 中增加一个servlet和servlet-mapping标签
-
-
Spring Boot
<dependency> <groupId>com.github.core-lib.httpdoc</groupId> <artifactId>httpdoc-spring-boot</artifactId> <version>v1.5.3</version> </dependency>
-
如果是Spring Boot项目则不需要上面SpringMVC的两个配置,实际上 Spring Boot 项目也没有web.xml文件来做配置。
-
只需要将httpdoc-spring-mvc依赖替换成下面的依赖并在项目入口主类上标注一个@EnableHttpdoc() 注解即可,对应的参数也可以在注解上设置。
-
参数说明
-
httpdoc 项目名称,缺省为HttpDoc
-
version 项目版本,缺省为1.0.0
-
description 项目描述,可以用套起来并使用HTML标签语法
-
protocol 访问协议,http或https,缺省为request.getProtocol();
-
hostname 主机名,缺省为request.getServerName();
-
port 端口号,缺省为request.getServerPort();
-
context 容器路径,缺省为request.getContextPath();
-
dateFormat 日期格式,缺省为yyyy-MM-dd HH🇲🇲ss
-
translator 文档翻译器,缺省为自动匹配当前项目的WEB框架
-
interpreter 文档解释器,缺省为源码解释器
-
serializer 文档序列化器,缺省为JSON序列化器,所以项目中需要依赖jackson-databind
在线示例
项目中的httpdoc-sample模块就是一个HttpDoc + SpringMVC的一个标准示例,可checkout后查看源码和编译运行查看效果,也可立即预览:JSON-Editor: httpdoc-ui TextArea: httpdoc-ui-v1
变更记录
-
v1.5.8
-
增加Schema的全局设置
-
适配递归Schema的问题
-
-
v1.5.7
-
增加JSONEditor的前端实现
-
增加@style标签用于控制参数展示的样式
-
-
v1.5.6
-
修复带中文或空格路径的解析失败bug
-
适配Unix系统路径分隔符
-
注释读取日志显示
-
-
v1.5.5
-
增加Lifecycle接口让实现类可以监听initial和destroy事件以及用户配置信息
-
-
v1.5.4
-
极大提升源码注释解析速度
-
修复spring-boot模块的依赖,增加spring-mvc依赖
-
-
v1.5.3
-
优化项目依赖让项目集成更简单
-
默认采用JSON文档序列化器
-
-
v1.5.2
-
第一个正式版发布
-
-
v1.5.1
-
增加示例模块
-
增加README.md
-