2 Star 8 Fork 2

NoBugBoy / YDoc

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

YDoc一款低侵入性、简洁并同时支持SwaggerUi和YApi的文档生成器

使用过程出现问题,可以提一个issues描述一下,看到后会更正。

1.1.5版本需要配置 ydoc.headers= 这是个bug,下个版本会修复

使用Springboot 2.6.* 的朋友需要在配置文件新增一条参数

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

final版本使用了新的ui库

       <dependency>
            <groupId>com.github.nobugboy</groupId>
            <artifactId>ydoc-spring-boot-starter</artifactId>
            <version>1.1.6.final</version>
        </dependency>

充分利用springboot自有注解来对文档进行描述的一款文档生成器。 让我们抛弃大量注解和配置一起拥抱简洁。

YDoc图文版使用教程,方便更好的理解和使用。

B站视频使用教程

引言

每当工程需要接口文档时,总会使用Swagger一类的restfulApi文档生成工具,相信很多人在使用时都会被它的一些注解和配置恶心到,如果工程对代码规范无要求还能作为注释来看,如果需要再写Javadoc注释就无形中增加了工作量,为了更加简单的使用我写了一款基于spring-boot-starter的依赖库,它基于YApi平台可以统一管理api文档和权限控制,mock数据等。

1. 对比其他文档生成器

这里举两种java平台常用的api文档生成器。

1.JDoc

JDoc是根据文档注释去生成api文档的工具,需要遵循JDoc定义的文档规范进行书写才能生成对应的接口文档,不支持mock数据,权限管理等,不能集中管理Api,强制依赖于Javadoc规范实现,静态页面部署不方便,对离线支持好。

  • 优点是只需要写Javadoc即可无需引入额外配置。
  • 缺点是强制依赖于Javadoc规范,对api测试不友好,生成需额外操作。

2.Swagger2

Swagger是基于注解形式生成api文档的工具,对接口的参数,返回值等都需要加对应的注释才能生成对应的api文档,支持api测试,不支持mock数据,权限管理等,不能集中管理Api,不方便离线,随程序部署而部署。

  • 优点是操作简单,接口生成的比较好,随程序部署而部署使用方便。
  • 缺点是集成麻烦,依赖大量注解,增加开发成本。

3.YDoc

Ydoc是一款基于spring-boot-starter的依赖库,轻量级,不依赖注释,少量依赖注解和使用规范,整体依赖于YApi接口可视化平台,可使用YApi的所有特征,与程序部署分离可集中化管理,支持权限控制等,集成快速高效,配置依赖,加上两行配置程序启动时即可自动生成。

  • 优点是可使用Swagger和YApi平台的特性,侵入性更低,快速集成,引入依赖配置参数即可,不需要额外配置类插拔更方便。
  • 缺点是少量依赖注解和使用规范,仅支持spring-boot工程

2. YDoc的使用方法(基于YApi版本1.9.2)

  1. 需搭建YApi文档平台(YApi官方文档
  2. 项目中引用ydoc-spring-boot-starter依赖
  3. 配置 ydoc.enable = true
  4. 如果想要使用YApi,需在配置文件中配置YApi的url,以及项目的token
  5. 如果想要使用Swagger-bootstrap-ui 需加@EnableSwagger2,访问/doc.html即可使用
  6. 都想要?以上都配置即可。
  7. 额外配置?扫包?不存在的,启动即可使用

如果不能直接依赖说明还没有同步到中央maven(1.0.2才支持Swagger-bootstrap-ui )

YDoc版本更新说明

  1. 1.0.1支持YDoc方式生成YApi文档
  2. 1.0.2支持YDoc方式生成Swagger文档
  3. 1.0.3支持Swagger原生注解生成Swagger文档,并同步导入到YApi(方便已经使用了swagger原生注解,但是还想快速导入YApi的用户,拒绝使用YApi轮训导入从我做起
  4. 1.0.4支持自动化测试,钉钉提醒和微服务
  5. 1.0.5支持非native模式生成swagger文档,邮件提醒,web测试报告展示
  6. 1.0.6修复bug
  7. 1.0.7修复匿名内部类解析问题 参考 https://juejin.cn/post/6994640102974554143
  8. 1.0.8修复issue问题 https://github.com/NoBugBoy/YDoc/issues/8 tag: https://github.com/NoBugBoy/YDoc/releases/tag/1.0.8
  9. 1.0.9修复url被覆盖问题,缩小banner
  10. 1.1.0修复返回值泛型被覆盖的问题 https://github.com/NoBugBoy/YDoc/issues/12
  11. 1.1.1修复返回值R<List>解析失败的问题&深层嵌套解析内部属性失败&修复返回值List解析错误
  12. 1.1.2新增通用公共headers配置,和解析@RequestHeader注解
  13. 1.1.3修复不配置headers会空指针问题,和参数必填显示为false等问题
  14. 1.1.4修复requestbody对象内参数使用ParamDesc的required修饰时没有正确的显示在文档上
  15. 1.1.5修复代理类无法被正常生成api的问题&代码重构
  16. 1.1.6修复1.1.5的bug
       <dependency>
            <groupId>com.github.nobugboy</groupId>
            <artifactId>ydoc-spring-boot-starter</artifactId>
            <version>1.1.6</version>
        </dependency>

final版本是对应正式版本并使用了新的ui库(luck-ui) 建议尝试使用该版本 https://github.com/NoBugBoy/YdocLuckyUi

       <dependency>
            <groupId>com.github.nobugboy</groupId>
            <artifactId>ydoc-spring-boot-starter</artifactId>
            <version>1.1.6.final</version>
        </dependency>
配置名 是否必须
ydoc.token YApi项目中生成的token
ydoc.host YApi的url,例http://localhost:3000
ydoc.headers 配置所有api公共header参数(多个用,分割)
ydoc.enable 程序启动时是否同步到YApi平台
ydoc.print 程序启动时是否打印离线JSON(可手动导入到YApi或其他文档平台)
ydoc.swagger-native 是否启用Swagger原生配置生成文档(方便已经集成了swagger得用户)
ydoc.cloud 是否开启微服务模式
ydoc.autoTest 是否开启自动化测试
ydoc.test.name 自动化测试集合名称,可以多个(自动化测试时使用)
ydoc.id yapi项目id,在设置中查看(自动化测试时使用)
ydoc.yapi.user.email yapi登录邮箱(自动化测试时使用)
ydoc.yapi.user.password yapi登录邮箱密码(自动化测试时使用)
ydoc.accessToken 钉钉机器人token(自动化测试时使用)
ydoc.email.host 邮件服务器(自动化测试时使用)
ydoc.email.password 邮箱pop3,smtp密码(自动化测试时使用)
ydoc.email.password 邮箱pop3,smtp密码(自动化测试时使用)

注意当开启了swagger-native,需要将原工程的swagger依赖删除即可。(YDoc内部使用swagger3.0)

3. YApi的使用步骤(导入YApi,YDoc方式或者原生swagger都支持)

  1. 在搭建好的YApi平台上创建好对应工程的项目
  2. 点开项目,设置-token配置,复制好token粘贴到Java工程的对应配置上
  3. 配置ydoc.enable = true,yapi-host,yapi-token
  4. 启动应用即可
  5. 回到YApi页面,文档生产完毕

4. Swaager3的使用步骤(YDoc生成方式)

  1. 开启@EnableSwagger2
  2. 使用YDoc注解生成方式配置项目
  3. 配置ydoc.enable = true
  4. 启动应用访问 /doc.html

5. 原生Swaager的使用(方便已经使用原生swagger注解的项目)

  1. 和普通swagger一样配置即可,需要配置扫包和swagger注解等
  2. 配置ydoc.enable = true,swagger-native=true
  3. 启动应用访问 /doc.html

6. 自动化测试的使用

  1. 配置测试集合,并定义名称(英文)
  2. 配置ydoc.autoTest=true,ydoc.id,ydoc.test.name
  3. 启动应用自动开始测试(异步)
  4. 测试结束发送报告,参考下面的文章链接

1.0.4支持微服务模式,自动化测试,推送钉钉报告1.0.5非原生模式也支持swagger页面,邮件推送web页面展示

5. YDoc方式生成描述

抛弃大量Swagger注解和配置,仅需在SpringBootWeb开发时必须注解上加额外参数对api或参数进行描述,大大减少了对工程的侵入性,简化开发流程

注解
@RestController 注解中value描述controller的作用,默认为controller名
@RequestMapping 注解中name描述该api的作用,在类上加跟路径时不需要name
@PathVariable 注解中name描述该参数的作用
@GetMapping 注解中name描述该api的作用
@PostMapping 注解中name描述该api的作用
@DeleteMapping 注解中name描述该api的作用
@PutMapping 注解中name描述该api的作用
@RequestHeader 注解中name描述该api的作用

@ParamDesc与@ParamIgnore为YDoc额外的自有注解,其余为SpringBoot的注解,@ParamDesc用来标识实体中参数的描述,@ParamIgnore用来忽略参数不参与生成文档,如不加参数描述则默认为参数的名称。

注解
@ParamDesc 注解中value描述该参数的描述,required是否必须
@ParamIgnore 忽略参数

6. Enum类型

对于Swagger中比较头疼的Enum类型参数描述做了一些优化处理,如果enum类型值,需要在enum中重写toString方法,返回一个字符串作为描述参数,该方式自由度较高,对于code和message可以很好地进行描述。

7.使用YDoc规范建议

  1. 无论是什么请求,如果使用对象接收对象内的基本类型建议使用包装类
  2. 建议在参数上加@ParamDesc用来描述作用
  3. spring提供的注解再原有开发习惯上加name,用来描述RestController或Api的作用
  4. 如有特殊参数例如Bindingresult,登录的用户实体等使用@ParamIgnore进行忽略
  5. 最好不要对象套对象自己比如U -> List 这种

7.话外音

详细步骤请参考YDoc使用图文教程

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

YDoc一款低侵入性、简洁并同时支持SwaggerUi和YApi的文档生成器 展开 收起
Java
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Java
1
https://gitee.com/nobugboy/YDoc.git
git@gitee.com:nobugboy/YDoc.git
nobugboy
YDoc
YDoc
main

搜索帮助

14c37bed 8189591 565d56ea 8189591