接口文档解决方案!企业级的接口文档管理平台!

是个陈序员 2024-08-19 17:16:34

大家好,我是 Java陈序员。

在企业开发中,涉及到很多个项目,每个项目都有一套自己的接口文档,维护起来不是很方便,需要一个统一的接口文档管理平台来进行管理。

今天,给大家介绍一个开源的企业级接口文档管理平台!

关注微信公众号:【Java陈序员】,获取开源项目分享、AI副业分享、超200本经典计算机电子书籍等。

项目介绍

Torna —— 一款接口文档解决方案,目标是让接口文档管理变得更加方便、快捷。采用团队协作的方式管理和维护接口文档,将不同形式的文档纳入进来统一维护。

Torna 作为一款企业级接口文档管理平台,实现了统一管理项目接口文档的功能,并且支持在线调试、游客预览。

此外,可以使用 smart-doc 无侵入完成 Java 源代码和注释提取生成 API 文档,然后自动将文档推送到 Torna 接口文档管理平台,从而实现接口预览、接口调试。

smart-doc 的介绍详见:

如果一些旧项目使用 Postman、 Swagger 或者 SpringDoc 来进行接口文档管理,Torna 也提供了对应的插件来集成!

功能特色:

文档管理:支持接口文档增删改查、导入导出、OpenAPI接入、字典管理、接口调试权限管理:以项目组的形式管理接口,各项目组之间接口互不影响,同时有访客、开发者、管理员三种角色,每种角色有用不同权限双模式:提供【管理模式】、【浏览模式】双模式,管理模式用来编辑文档内容,浏览模式纯粹查阅文档,界面无其它元素干扰界面预览

登录

空间列表

项目列表

应用管理

添加文档

文档预览

接口调试

接口Mock

常量管理

版本管理

预览模式

快速上手前置准备

开发环境:

Java8MySQL5.6.5+Maven3Node.js12

拉取代码:

git clone https://gitee.com/durcframework/torna.git

目录结构:

front: 前端工程plugin: 插件script: 辅助脚本sdk: OpenAPI对应的SDKserver: 服务端工程mysql.sql:数据库脚本后端服务

1、将整个项目以 Maven 项目的形式导入到 IDEA 中

2、执行脚本 mysql.sql 初始化数据

3、修改配置文件 server/boot/src/main/resources/application.properties 中的数据库配置信息

4、运行主启动类 server/boot/src/main/java/cn/torna/TornaApplication.jav 启动项目

前端服务

1、进入前端项目

cd front

2、安装依赖

npm isntall

3、启动项目

npm run dev

4、浏览器访问:

http://localhost:9530/#/

默认用户名密码:admin/123456

部署 Torna 可以使用源码打包的方式进行部署,也可以使用项目提供的脚本进行部署,或者是使用 Docker 的方式进行部署,具体的部署方式可以参考官方文档。

使用 smart-doc 推送文档

使用 smart-doc 可以无侵入完成提取注释生成 API 文档,并自动将文档推送到 Torna 平台。

smart-doc 插件是依赖于接口的源代码进行分析和生成文档,因此需按照 JavaDoc 的标准编写注释。

1、在 Torna 平台先创建一个项目,在 OpenAPI 中获取请求路径和 token

2、在项目中引入 smart-doc 插件

<plugins> <!-- smart-doc插件 --> <plugin> <groupId>com.ly.smart-doc</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>3.0.2</version> <configuration> <!--指定生成文档的使用的配置文件--> <configFile>${basedir}/src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>收银台后台服务</projectName> </configuration> <executions> <execution> <phase>package</phase> </execution> </executions> </plugin></plugins>

3、在项目的 resources 目录下添加一个 smart-doc.json 文件

{ "outPath": "target/doc", "projectName": "收银台后台服务", "packageFilters": "com.codechen.pay.controller.*", "openUrl": "http://localhost:9530/api", "appToken": "27ffa73c8794454abc58f481ada23766", "debugEnvName":"本地环境", "debugEnvUrl":"http://127.0.0.1:8080", "tornaDebug": true, "replace": true}

openUrl 和 appToken 在应用的 OpenAPI 中获取。

4、运行插件,将文档推送到 Torna 平台

或者在项目根目录输入 Maven 命令:mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :shop-web -am

除了使用 smart-doc 插件推送文档外,项目还提供了 Swagger 文档、SpringDoc 文档推送的插件,相应的集成可参考项目文档。

Torna 可以说是一个功能十分强大的接口管理平台,完美适用于企业级开发。如果需要搭建一个企业级的接口管理平台,可以考虑使用 Torna.

项目地址:https://gitee.com/durcframework/torna在线文档:https://torna.cn/最后

推荐的开源项目已经收录到 GitHub 项目,欢迎 Star:

https://github.com/chenyl8848/great-open-source-project

或者访问网站,进行在线浏览:

https://chencoding.top:8090/#/

大家的点赞、收藏和评论都是对作者的支持,如文章对你有帮助还请点赞转发支持下,谢谢!

0 阅读:2

是个陈序员

简介:感谢大家的关注