Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/core-lib/httpdoc

基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线测试，文档阅览以及SDK导出框架，支持Spring-Boot和Spring-MVC
https://github.com/core-lib/httpdoc

http javadoc sdk spring-boot spring-mvc

Last synced: about 2 months ago
JSON representation

基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线测试，文档阅览以及SDK导出框架，支持Spring-Boot和Spring-MVC

Host: GitHub
URL: https://github.com/core-lib/httpdoc
Owner: core-lib
License: apache-2.0
Created: 2018-06-15T06:47:50.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2022-12-16T12:04:16.000Z (about 2 years ago)
Last Synced: 2023-03-04T17:27:53.156Z (almost 2 years ago)
Topics: http, javadoc, sdk, spring-boot, spring-mvc
Language: Java
Homepage: http://106.13.16.25/httpdoc-sample/httpdoc-ui/index.html
Size: 6.46 MB
Stars: 26
Watchers: 3
Forks: 14
Open Issues: 28
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# HttpDoc [![](https://www.jitpack.io/v/core-lib/httpdoc.svg)](https://www.jitpack.io/#core-lib/httpdoc)
##### 基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线测试，文档阅览以及SDK导出框架，支持Spring-Boot和Spring-MVC
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)

## 功能特性
* 基础功能无需为配合HttpDoc框架而多写一句代码，甚至连doc注释都不必写，即可拥有项目的API文档和测试界面。
* 遵循 [RFC 2616 HTTP/1.1](https://tools.ietf.org/html/rfc2616) 规范，适配主流后台WEB框架。
* 拓展多个 Java Doc 注释标签，满足不同的文档阅览及在线测试需求。
* 一键生成SDK，支持多个平台，让前后台以及跨平台对接变得更简单。
* WEB服务器无关，同时支持 Spring Boot 命令方式启动。
* 支持 Maven Gradle 或JAR包依赖。

## 环境依赖
JDK 1.7 +

## 集成步骤
### Maven
1. 引入依赖
```xml

jitpack.io
https://jitpack.io

com.github.core-lib.httpdoc
httpdoc-spring-mvc
v1.8.1

com.sun
tools
1.8
system
${env.JAVA_HOME}/lib/tools.jar

```

2. 配置插件
```xml

org.apache.maven.plugins
maven-resources-plugin
3.1.0

UTF-8

copy-src
process-sources

copy-resources

${project.build.directory}/classes

${basedir}/src/main/java

```

3. 配置参数
* SpringMVC
* web.xml 中增加一个servlet和servlet-mapping标签
```xml

httpdoc
io.httpdoc.web.HttpdocServletSupport

packages
io.httpdoc.sample

httpdoc
项目名称

version
项目版本

description

dateFormat
yyyy-MM-dd HH:mm:ss

1

httpdoc
/httpdoc.json

```
* spring-servlet.xml 中增加一个标签以允许浏览器访问HttpDoc的页面静态资源
```xml

```

* Spring Boot
* 如果是Spring Boot项目则不需要上面SpringMVC的两个配置，实际上 Spring Boot 项目也没有web.xml文件来做配置。
* 只需要将httpdoc-spring-mvc依赖替换成下面的依赖并在项目入口主类上标注一个@EnableHttpdoc() 注解即可，对应的参数也可以在注解上设置。
```xml

com.github.core-lib.httpdoc
httpdoc-spring-boot
v1.8.1

```
```java
@SpringBootApplication
@EnableHttpdoc(
packages = {"io.httpdoc.sample"},
httpdoc = "服务名称",
version = "服务版本",
description = "服务描述-支持HTML语法。"
)
public class HttpdocApplication {
public static void main(String[] args) {
SpringApplication.run(HttpdocApplication.class, args);
}
}
```

## 参数说明
| 参数名称 | 参数说明 | 缺省值 |
| :------- | :------- | :----- |
| packages | 源码包名 | 必填参数，支持配置多个，通过英文逗号，空格及换行符拆分，支持递归搜索 |
| 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:mm:ss |
| translator | 文档翻译器 | 自动匹配当前项目的WEB框架 |
| interpreter | 文档解释器 | 源码解释器 |
| serializer | 文档序列化器| JSON序列化器，所以项目中需要依赖jackson-databind |

## 在线示例
项目中的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)

## 变更记录
* v1.8.1
* 适配应用被反向代理后前端测试域名获取不正确问题
* v1.8.0
* 修复BaseURL与接口相对路径问题
* v1.7.9
* 修复BaseURL与接口相对路径问题
* v1.7.8
* UI 默认采用 grid 方式展示API参数
* v1.7.7
* 升级[LoadKit](https://github.com/core-lib/loadkit)依赖版本解决ANT表达式无法正确匹配**/*通配符的问题
* v1.7.6
* ObjC 生成时采用 BOOL 代替 bool
* v1.7.5
* 测试界面空对象/空值参数不参与json序列化
* v1.7.4
* iOS SDK 生成bug修复
* v1.7.3
* boolean 类型字段 getter 方法从 get 改为 is 开头
* v1.7.2
* retrofit2 客户端增加 RxJava 的支持
* v1.7.1
* 整理 pom 依赖
* 解决SDK导出中文乱码问题
* 升级 Jestful 依赖版本
* v1.7.0
* 修复 Retrofit 及 Retrofit 2 生成 API 方法时没有带上参数注释问题
* v1.6.9
* 增加对 retrofit 1 的支持
* 修改 retrofit 2 模块的包名
* v1.6.8
* 可通过参数配置SDK导出形式
* 开放更多第三方拓展能力
* v1.6.7
* 修复当没有源码时重复构建文档的bug
* 重构多个 Translator 实现使之可以更容易拓展
* v1.6.6
* 修复生成Model中包含java关键字的问题
* Controller中增加别名支持
* v1.6.5
* 按照bean属性定义的顺序排列
* 采用LoadKit替代Detector
* v1.6.4
* 优化SDK导出的压缩包结构
* v1.6.3
* 增加packages参数用于筛选需要解析的源码包，支持多个源码包和递归搜索。
* 优化源码提取逻辑，适配更多启动模式。
* v1.6.2
* 升级detector框架依赖
* v1.6.1
* UI 展示的优化
* v1.6.0
* 采用detector框架的方式进行多模块集成
* v1.5.9
* 采用SoftReference来引用文档对象，避免空闲时占用过多JVM内存。
* 增加Exporter接口用于导出SDK
* 界面上可以下载SDK
* 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

## 协议声明
[Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)

## 联系作者
QQ 646742615 不会钓鱼的兔子