{"id":19237525,"url":"https://github.com/core-lib/httpdoc","last_synced_at":"2025-09-14T15:26:22.714Z","repository":{"id":39962270,"uuid":"137451275","full_name":"core-lib/httpdoc","owner":"core-lib","description":"基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线测试，文档阅览以及SDK导出框架，支持Spring-Boot和Spring-MVC","archived":false,"fork":false,"pushed_at":"2022-12-16T12:04:16.000Z","size":6776,"stargazers_count":25,"open_issues_count":28,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-09T00:35:07.410Z","etag":null,"topics":["http","javadoc","sdk","spring-boot","spring-mvc"],"latest_commit_sha":null,"homepage":"http://106.13.16.25/httpdoc-sample/httpdoc-ui/index.html","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/core-lib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-15T06:47:50.000Z","updated_at":"2023-04-20T02:29:13.000Z","dependencies_parsed_at":"2022-08-25T09:10:25.740Z","dependency_job_id":null,"html_url":"https://github.com/core-lib/httpdoc","commit_stats":null,"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"purl":"pkg:github/core-lib/httpdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-lib%2Fhttpdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-lib%2Fhttpdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-lib%2Fhttpdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-lib%2Fhttpdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/core-lib","download_url":"https://codeload.github.com/core-lib/httpdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-lib%2Fhttpdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275122979,"owners_count":25409352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http","javadoc","sdk","spring-boot","spring-mvc"],"created_at":"2024-11-09T16:27:07.559Z","updated_at":"2025-09-14T15:26:22.658Z","avatar_url":"https://github.com/core-lib.png","language":"Java","readme":"# HttpDoc [![](https://www.jitpack.io/v/core-lib/httpdoc.svg)](https://www.jitpack.io/#core-lib/httpdoc)\r\n##### 基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线测试，文档阅览以及SDK导出框架，支持Spring-Boot和Spring-MVC\r\nJSON-Editor: [httpdoc-ui](http://106.13.16.25/httpdoc-sample/httpdoc-ui/index.html) TextArea: [httpdoc-ui-v1](http://106.13.16.25/httpdoc-sample/httpdoc-ui-v1/index.html)\r\n\r\n## 功能特性\r\n* 基础功能无需为配合HttpDoc框架而多写一句代码，甚至连doc注释都不必写，即可拥有项目的API文档和测试界面。\r\n* 遵循 [RFC 2616 HTTP/1.1](https://tools.ietf.org/html/rfc2616) 规范，适配主流后台WEB框架。\r\n* 拓展多个 Java Doc 注释标签，满足不同的文档阅览及在线测试需求。\r\n* 一键生成SDK，支持多个平台，让前后台以及跨平台对接变得更简单。\r\n* WEB服务器无关，同时支持 Spring Boot 命令方式启动。\r\n* 支持 Maven Gradle 或JAR包依赖。\r\n\r\n## 环境依赖\r\nJDK 1.7 +\r\n\r\n## 集成步骤\r\n### Maven\r\n1. 引入依赖\r\n```xml\r\n\u003cproject\u003e\r\n    \u003c!-- 设置 jitpack.io 仓库 --\u003e\r\n    \u003crepositories\u003e\r\n        \u003crepository\u003e\r\n            \u003cid\u003ejitpack.io\u003c/id\u003e\r\n            \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\r\n        \u003c/repository\u003e\r\n    \u003c/repositories\u003e\r\n\r\n    \u003cdependencies\u003e\r\n        \u003c!-- 添加 HttpDoc 依赖 --\u003e\r\n        \u003cdependency\u003e\r\n            \u003cgroupId\u003ecom.github.core-lib.httpdoc\u003c/groupId\u003e\r\n            \u003cartifactId\u003ehttpdoc-spring-mvc\u003c/artifactId\u003e\r\n            \u003cversion\u003ev1.8.1\u003c/version\u003e\r\n        \u003c/dependency\u003e\r\n        \r\n        \u003c!-- 添加JDK的tools.jar依赖用于解析源码注释，采用这种方式部署到Tomcat时需要往Tomcat的lib目录增加该tools.jar --\u003e\r\n        \u003cdependency\u003e\r\n            \u003cgroupId\u003ecom.sun\u003c/groupId\u003e\r\n            \u003cartifactId\u003etools\u003c/artifactId\u003e\r\n            \u003cversion\u003e1.8\u003c/version\u003e\r\n            \u003cscope\u003esystem\u003c/scope\u003e\r\n            \u003csystemPath\u003e${env.JAVA_HOME}/lib/tools.jar\u003c/systemPath\u003e\r\n        \u003c/dependency\u003e\r\n        \u003c!-- 当然还有很多种方式来依赖tools.jar，例如上传到自己的私服或从别的仓库中依赖进来 --\u003e\r\n    \u003c/dependencies\u003e\r\n\u003c/project\u003e\r\n```\r\n\r\n2. 配置插件\r\n```xml\r\n\u003c!-- 由于框架基于源码注释解析来实现，所以保留源码是基础，如果只想要在线测试而没有文档阅览的需求，可不必添加该插件。--\u003e\r\n\u003c!-- 如果项目是多模块项目，需要被解析的源码类分散在多模块中，则其他模块也需要配置该插件，或在父项目的pom.xml中配置该插件。--\u003e\r\n\u003cplugin\u003e\r\n    \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\r\n    \u003cartifactId\u003emaven-resources-plugin\u003c/artifactId\u003e\r\n    \u003cversion\u003e3.1.0\u003c/version\u003e\r\n    \u003cconfiguration\u003e\r\n        \u003cencoding\u003eUTF-8\u003c/encoding\u003e\r\n    \u003c/configuration\u003e\r\n    \u003cexecutions\u003e\r\n        \u003cexecution\u003e\r\n            \u003cid\u003ecopy-src\u003c/id\u003e\r\n            \u003cphase\u003eprocess-sources\u003c/phase\u003e\r\n            \u003cgoals\u003e\r\n                \u003cgoal\u003ecopy-resources\u003c/goal\u003e\r\n            \u003c/goals\u003e\r\n            \u003cconfiguration\u003e\r\n                \u003coutputDirectory\u003e${project.build.directory}/classes\u003c/outputDirectory\u003e\r\n                \u003cresources\u003e\r\n                    \u003cresource\u003e\r\n                        \u003cdirectory\u003e${basedir}/src/main/java\u003c/directory\u003e\r\n                    \u003c/resource\u003e\r\n                \u003c/resources\u003e\r\n            \u003c/configuration\u003e\r\n        \u003c/execution\u003e\r\n    \u003c/executions\u003e\r\n\u003c/plugin\u003e\r\n```\r\n\r\n3. 配置参数\r\n* SpringMVC\r\n    * web.xml 中增加一个servlet和servlet-mapping标签\r\n    ```xml\r\n    \u003cweb-app\u003e\r\n        \u003cservlet\u003e\r\n            \u003cservlet-name\u003ehttpdoc\u003c/servlet-name\u003e\r\n            \u003cservlet-class\u003eio.httpdoc.web.HttpdocServletSupport\u003c/servlet-class\u003e\r\n            \u003cinit-param\u003e\r\n                \u003cparam-name\u003epackages\u003c/param-name\u003e\r\n                \u003cparam-value\u003eio.httpdoc.sample\u003c/param-value\u003e\r\n            \u003c/init-param\u003e\r\n            \u003cinit-param\u003e\r\n                \u003cparam-name\u003ehttpdoc\u003c/param-name\u003e\r\n                \u003cparam-value\u003e项目名称\u003c/param-value\u003e\r\n            \u003c/init-param\u003e\r\n            \u003cinit-param\u003e\r\n                \u003cparam-name\u003eversion\u003c/param-name\u003e\r\n                \u003cparam-value\u003e项目版本\u003c/param-value\u003e\r\n            \u003c/init-param\u003e\r\n            \u003cinit-param\u003e\r\n                \u003cparam-name\u003edescription\u003c/param-name\u003e\r\n                \u003cparam-value\u003e\r\n                    \u003c![CDATA[\r\n                        项目描述(可以内嵌HTML标签)\r\n                    ]]\u003e\r\n                \u003c/param-value\u003e\r\n            \u003c/init-param\u003e\r\n            \u003cinit-param\u003e\r\n                \u003cparam-name\u003edateFormat\u003c/param-name\u003e\r\n                \u003cparam-value\u003eyyyy-MM-dd HH:mm:ss\u003c/param-value\u003e\r\n            \u003c/init-param\u003e\r\n            \u003cload-on-startup\u003e1\u003c/load-on-startup\u003e\r\n        \u003c/servlet\u003e\r\n        \r\n        \u003cservlet-mapping\u003e\r\n            \u003cservlet-name\u003ehttpdoc\u003c/servlet-name\u003e\r\n            \u003curl-pattern\u003e/httpdoc.json\u003c/url-pattern\u003e\r\n        \u003c/servlet-mapping\u003e\r\n    \u003c/web-app\u003e\r\n    ```\r\n    * spring-servlet.xml 中增加一个标签以允许浏览器访问HttpDoc的页面静态资源\r\n    ```xml\r\n    \u003cmvc:resources mapping=\"/httpdoc-ui/**\" location=\"classpath:/META-INF/resources/httpdoc-ui/\"/\u003e\r\n    ```\r\n    \r\n* Spring Boot\r\n    * 如果是Spring Boot项目则不需要上面SpringMVC的两个配置，实际上 Spring Boot 项目也没有web.xml文件来做配置。\r\n    * 只需要将httpdoc-spring-mvc依赖替换成下面的依赖并在项目入口主类上标注一个@EnableHttpdoc() 注解即可，对应的参数也可以在注解上设置。\r\n    ```xml\r\n    \u003cdependency\u003e\r\n      \u003cgroupId\u003ecom.github.core-lib.httpdoc\u003c/groupId\u003e\r\n      \u003cartifactId\u003ehttpdoc-spring-boot\u003c/artifactId\u003e\r\n      \u003cversion\u003ev1.8.1\u003c/version\u003e\r\n    \u003c/dependency\u003e\r\n    ```\r\n    ```java\r\n    @SpringBootApplication\r\n    @EnableHttpdoc(\r\n          packages = {\"io.httpdoc.sample\"},\r\n          httpdoc = \"服务名称\", \r\n          version = \"服务版本\", \r\n          description = \"服务描述-支持HTML语法。\"\r\n    )\r\n    public class HttpdocApplication {   \r\n        public static void main(String[] args) {\r\n            SpringApplication.run(HttpdocApplication.class, args);\r\n        }\r\n    }\r\n    ```\r\n    \r\n## 参数说明\r\n| 参数名称 | 参数说明 | 缺省值 |\r\n| :------- | :------- | :----- |\r\n| packages     | 源码包名    | 必填参数，支持配置多个，通过英文逗号，空格及换行符拆分，支持递归搜索 |\r\n| httpdoc      | 项目名称    | HttpDoc |\r\n| version      | 项目版本    | 1.0.0 |\r\n| description  | 项目描述    | 可以用\u003c![CDATA[]]\u003e套起来并使用HTML标签语法 |\r\n| protocol     | 访问协议    | http或https，缺省为request.getProtocol(); |\r\n| hostname     | 主机名      | request.getServerName(); |\r\n| port         | 端口号      | request.getServerPort(); |\r\n| context      | 容器路径    | request.getContextPath(); |\r\n| dateFormat   | 日期格式    | yyyy-MM-dd HH:mm:ss |\r\n| translator   | 文档翻译器  | 自动匹配当前项目的WEB框架 |\r\n| interpreter  | 文档解释器  | 源码解释器 |\r\n| serializer   | 文档序列化器| JSON序列化器，所以项目中需要依赖jackson-databind |\r\n\r\n## 在线示例\r\n项目中的httpdoc-sample模块就是一个HttpDoc + SpringMVC的一个标准示例，可checkout后查看源码和编译运行查看效果，也可立即预览：JSON-Editor: [httpdoc-ui](http://106.13.16.25/httpdoc-sample/httpdoc-ui/index.html) TextArea: [httpdoc-ui-v1](http://106.13.16.25/httpdoc-sample/httpdoc-ui-v1/index.html)\r\n\r\n## 变更记录\r\n* v1.8.1\r\n    * 适配应用被反向代理后前端测试域名获取不正确问题\r\n* v1.8.0\r\n    * 修复BaseURL与接口相对路径问题\r\n* v1.7.9\r\n    * 修复BaseURL与接口相对路径问题\r\n* v1.7.8\r\n    * UI 默认采用 grid 方式展示API参数\r\n* v1.7.7\r\n    * 升级[LoadKit](https://github.com/core-lib/loadkit)依赖版本解决ANT表达式无法正确匹配**/*通配符的问题\r\n* v1.7.6\r\n    * ObjC 生成时采用 BOOL 代替 bool\r\n* v1.7.5\r\n    * 测试界面 空对象/空值 参数不参与json序列化\r\n* v1.7.4\r\n    * iOS SDK 生成bug修复\r\n* v1.7.3\r\n    * boolean 类型字段 getter 方法从 get 改为 is 开头\r\n* v1.7.2 \r\n    * retrofit2 客户端 增加 RxJava 的支持\r\n* v1.7.1\r\n    * 整理 pom 依赖\r\n    * 解决SDK导出中文乱码问题\r\n    * 升级 Jestful 依赖版本\r\n* v1.7.0\r\n    * 修复 Retrofit 及 Retrofit 2 生成 API 方法时没有带上参数注释问题\r\n* v1.6.9\r\n    * 增加对 retrofit 1 的支持\r\n    * 修改 retrofit 2 模块的包名\r\n* v1.6.8\r\n    * 可通过参数配置SDK导出形式\r\n    * 开放更多第三方拓展能力\r\n* v1.6.7\r\n    * 修复当没有源码时重复构建文档的bug\r\n    * 重构多个 Translator 实现 使之可以更容易拓展\r\n* v1.6.6\r\n    * 修复生成Model中包含java关键字的问题\r\n    * Controller中增加别名支持\r\n* v1.6.5\r\n    * 按照bean属性定义的顺序排列\r\n    * 采用LoadKit替代Detector\r\n* v1.6.4\r\n    * 优化SDK导出的压缩包结构\r\n* v1.6.3\r\n    * 增加packages参数用于筛选需要解析的源码包，支持多个源码包和递归搜索。\r\n    * 优化源码提取逻辑，适配更多启动模式。\r\n* v1.6.2\r\n    * 升级detector框架依赖\r\n* v1.6.1\r\n    * UI 展示的优化\r\n* v1.6.0\r\n    * 采用detector框架的方式进行多模块集成\r\n* v1.5.9\r\n    * 采用SoftReference来引用文档对象，避免空闲时占用过多JVM内存。\r\n    * 增加Exporter接口用于导出SDK\r\n    * 界面上可以下载SDK\r\n* v1.5.8\r\n    * 增加Schema的全局设置\r\n    * 适配递归Schema的问题\r\n* v1.5.7\r\n    * 增加JSONEditor的前端实现\r\n    * 增加@style标签用于控制参数展示的样式\r\n* v1.5.6\r\n    * 修复带中文或空格路径的解析失败bug\r\n    * 适配Unix系统路径分隔符\r\n    * 注释读取日志显示\r\n* v1.5.5\r\n    * 增加Lifecycle接口让实现类可以监听initial和destroy事件以及用户配置信息\r\n* v1.5.4\r\n    * 极大提升源码注释解析速度\r\n    * 修复spring-boot模块的依赖，增加spring-mvc依赖\r\n* v1.5.3\r\n    * 优化项目依赖让项目集成更简单\r\n    * 默认采用JSON文档序列化器\r\n* v1.5.2\r\n    * 第一个正式版发布\r\n* v1.5.1\r\n    * 增加示例模块\r\n    * 增加README.md\r\n\r\n## 协议声明\r\n[Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)\r\n\r\n## 联系作者\r\nQQ 646742615 不会钓鱼的兔子\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcore-lib%2Fhttpdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcore-lib%2Fhttpdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcore-lib%2Fhttpdoc/lists"}