# Doc2Json **Repository Path**: aFang-share/doc2-json ## Basic Information - **Project Name**: Doc2Json - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-10-24 - **Last Updated**: 2025-10-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Doc2Json - 智能Java代码注释解析器 [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.7-green.svg)](https://spring.io/projects/spring-boot) [![Java](https://img.shields.io/badge/Java-17-blue.svg)](https://openjdk.java.net/projects/jdk17/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) 🚀 **零注解开发** - 智能解析Java代码注释，自动生成JSON Schema和OpenAPI文档 ## ✨ 核心特性 - 🎯 **零注解开发** - 无需添加Swagger等注解，直接从JavaDoc注释自动生成文档 - 🧠 **智能解析** - 自动解析JavaDoc注释和方法签名，提取丰富的文档信息 - 📄 **双输出** - 同时生成JSON Schema和OpenAPI文档，满足不同需求 - ⚡ **Spring Boot集成** - 无缝集成Spring生态，开箱即用，支持自动配置 - 🎨 **类型映射** - 完整的Java类型到JSON Schema类型映射 - ✅ **验证约束** - 自动解析JSR-303验证注解到Schema约束 - 🌐 **RESTful API** - 提供完整的REST API接口，支持在线生成文档 ## 🚀 快速开始 ### 添加依赖在你的Spring Boot项目中添加Doc2Json依赖： ```xml com.example Doc2Json 1.0.0 ``` ### 基本配置在`application.properties`或`application.yml`中配置： ```properties # 启用Doc2Json doc2json.enabled=true # 设置要扫描的基础包 doc2json.base-packages=com.example.yourpackage # 自动生成文档（可选） doc2json.auto-generate=true # OpenAPI文档配置 doc2json.openapi.title=我的API文档 doc2json.openapi.description=自动生成的API文档 doc2json.openapi.version=1.0.0 ``` ### 示例代码只需编写标准的Java代码和JavaDoc注释： ```java /** * 用户实体类 * 表示系统中的用户信息 * * @author Doc2Json * @since 1.0.0 */ public class User { /** * 用户ID，唯一标识符 * 系统自动生成的唯一ID */ private Long id; /** * 用户名，登录时使用 * 长度限制：3-50个字符，只能包含字母、数字和下划线 */ private String username; /** * 电子邮箱地址 * 用于接收通知和找回密码 * 格式：标准的电子邮件格式 */ private String email; // 构造函数、getter、setter... } ``` 控制器示例： ```java /** * 用户管理控制器 * 提供用户的增删改查功能 */ @RestController @RequestMapping("/api/users") public class UserController { /** * 获取所有用户信息 * 返回系统中的所有用户列表 * * @return 用户列表 */ @GetMapping public List getAllUsers() { // 实现逻辑 } /** * 创建新用户 * 创建一个新的用户账户 * * @param user 用户信息，请求体中的JSON对象 * @return 创建成功的用户信息 */ @PostMapping public User createUser(@RequestBody CreateUserRequest user) { // 实现逻辑 } } ``` ### 启动应用启动你的Spring Boot应用后，访问： - **文档首页**: http://localhost:8080 - **生成完整文档**: http://localhost:8080/api/doc2json/generate - **生成OpenAPI**: http://localhost:8080/api/doc2json/openapi - **健康检查**: http://localhost:8080/api/doc2json/health ## 📚 API接口 ### 核心接口 | 接口 | 方法 | 描述 | |-----|------|------| | `/api/doc2json/generate` | GET | 生成完整文档（JSON Schema + OpenAPI） | | `/api/doc2json/openapi` | GET | 生成OpenAPI 3.0文档 | | `/api/doc2json/schema/{className}` | GET | 为指定类生成JSON Schema | | `/api/doc2json/classes` | GET | 获取所有解析的类信息 | | `/api/doc2json/refresh` | POST | 刷新文档缓存 | | `/api/doc2json/health` | GET | 服务健康检查 | ### 参数说明 - `packages`: 要扫描的包路径，多个用逗号分隔，默认为`com.example` - `className`: 类的完整限定名，支持URL编码 ## 🏗️ 架构设计 ``` ┌─────────────────────────────────────────────────────────────┐ │ Doc2Json架构 │ ├─────────────────────────────────────────────────────────────┤ │ Web层 │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Doc2JsonController │ │ Web界面 │ │ │ └─────────────────┘ └─────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 服务层 │ │ ┌─────────────────┐ │ │ │ Doc2JsonService │ │ │ └─────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 生成器层 │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │JsonSchemaGenerator│ │OpenApiGenerator│ │ │ └─────────────────┘ └─────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 解析器层 │ │ ┌─────────────────┐ │ │ │ JavaDocParser │ │ │ └─────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 模型层 │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ ClassDocInfo │ │FieldDocInfo │ │ │ └─────────────────┘ └─────────────────┘ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │MethodDocInfo │ │ParameterDocInfo│ │ │ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## ⚙️ 配置选项 ### 完整配置示例 ```yaml doc2json: # 是否启用 enabled: true # 扫描包路径 base-packages: - com.example.controller - com.example.model # 自动生成策略 auto-generate: true strategy: ON_STARTUP # ON_STARTUP, ON_DEMAND, SCHEDULED # 输出配置 output: to-file: true directory: ./docs pretty-print: true # 过滤配置 filter: controllers-only: false include-private-methods: false exclude-packages: - com.example.test exclude-class-suffixes: - Test - Tests # OpenAPI配置 openapi: title: API文档 description: 自动生成的API文档 version: 1.0.0 server-url: http://localhost:8080 contact-email: support@example.com # JSON Schema配置 json-schema: include-metadata: true include-validation-constraints: true include-examples: true ``` ## 🎯 类型映射 Doc2Json支持完整的Java类型到JSON Schema类型映射： | Java类型 | JSON Schema类型 | 说明 | |---------|---------------|------| | `int`, `Integer`, `long`, `Long` | `integer` | 整数类型 | | `double`, `Double`, `float`, `Float` | `number` | 数值类型 | | `String` | `string` | 字符串类型 | | `boolean`, `Boolean` | `boolean` | 布尔类型 | | `Date`, `LocalDateTime`, `LocalDate` | `string` | 日期时间（带format） | | `List`, `T[]`, `Set` | `array` | 数组/集合类型 | | 自定义类 | `object` | 对象类型 | | 枚举类型 | `string` | 枚举值 | ## ✅ 验证约束支持 Doc2Json自动解析常见的JSR-303验证注解： | 注解 | Schema约束 | |------|------------| | `@NotNull`, `@NotEmpty` | `required: true` | | `@Size(min=3, max=50)` | `minLength: 3, maxLength: 50` | | `@Min(18)`, `@Max(120)` | `minimum: 18, maximum: 120` | | `@Pattern(regexp="...")` | `pattern: "..."` | | `@Email` | `format: "email"` | | `@Positive`, `@Negative` | 约束范围 | ## 🔧 高级用法 ### 自定义解析器 ```java @Component public class CustomJavaDocParser implements JavaDocParser { // 实现自定义解析逻辑 } ``` ### 自定义生成器 ```java @Component public class CustomJsonSchemaGenerator implements JsonSchemaGenerator { // 实现自定义生成逻辑 } ``` ### 编程式使用 ```java @Autowired private Doc2JsonService doc2JsonService; // 生成文档 Map docs = doc2JsonService.generateDocumentation("com.example"); // 生成单个类的Schema String schema = doc2JsonService.generateJsonSchema(User.class); // 生成OpenAPI文档 String openApi = doc2JsonService.generateOpenApiDocumentation("com.example"); ``` ## 🧪 测试运行测试： ```bash mvn test ``` 运行特定测试： ```bash mvn test -Dtest=Doc2JsonIntegrationTest ``` ## 📈 性能优化 - **缓存机制**: 支持类信息缓存，避免重复解析 - **增量更新**: 支持增量更新文档，只重新解析变更的类 - **异步生成**: 支持异步生成文档，提高响应速度 ## 🤝 贡献欢迎提交Issue和Pull Request！ 1. Fork 本项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交变更 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 开启 Pull Request ## 📄 许可证本项目采用 [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) 许可证。 ## 🙏 致谢 - [JavaParser](https://javaparser.org/) - 用于解析Java源码 - [Spring Boot](https://spring.io/projects/spring-boot) - 提供自动配置支持 - [Jackson](https://github.com/FasterXML/jackson) - JSON处理 - [Reflections](https://github.com/ronmamo/reflections) - 反射工具 ## 📞 联系方式 - 项目主页: https://gitee.com/aFang-share/doc2-json.git - 问题反馈: https://gitee.com/aFang-share/doc2-json.git/issues - 邮箱: aFang-share@qq.com --- ⭐ 如果这个项目对你有帮助，请给我们一个Star！