有没有开源的java的接口文档管理工具

Posted 2023-04-17

参考技术A

有没有开源的java的接口文档管理工具, 有没有开源的文档管理系统？什么公司开发的？

我们用的是易度文档管理系统，这个是开源的，其他的不是很知道，好像不多，别的，

有没有免费的文档管理工具？

致得E6就有免费版的，很好用的，尤其是检索很给力，你可以试试！

有免费的文档管理工具吗?

你去是试下：edodocs：（易度）文档管理软件，去百度搜一下吧。

什么文档管理工具好

你试试：
idoc(多可)文档管理软件
到网上搜一下吧，有免费版，十用户之内的可以免费用，功能上没有限制

我需要一个文档管理工具

你做一个数据库，可以实时查询了

求专业的项目文档管理工具?

项目文档管理工具可以选8Manage项目管理系统，支持文档上传、可交付成果归档、文档模板复制等，功能比较实用的

linux有什么好的文档管理工具吗

CLI终端下有MidnightCommander（mc）。
GUI下有nautilus（gnome风格）、nemo、dolphin（kde风格）、thunar（xfce风格）、konqueror（kde）等等。
使用命名查看更多：

文档管理工具的官网是什么

我不知道为什么？官网回答不上，您只能用谷歌直接搜索了，金柜项目文档管理软件系统。其实挺想直接告诉您的，我也不知道为什么，就是回答不上。

有没有用Python编写的开源协同工作管理工具

不要求，但是你简单发布的话，因为python是脚本，所以别人就一定能拿到源代码（得到源代码和开源不一样）。你要不想公开你的源代码，你可以编译以后再发布。

API开源免费接口管理

接口文档管理平台

该平台主要用于整合后端各系统的服务，每个空间根据用户的空间权限，可以对接口文档进行不同层度的操作。

该平台涵盖了：

• 接口文档导入（基本不用额外代码）
• 权限管理
• 调试
• 格式化导出

主要技术：

• swagger 或 smart-doc
• torna

接口文档以系统自动生成为主，除非不能进行自动更新时，则少量手动更新，但是并不建议手动更新，以免自动更新后覆盖更新内容。

空间及项目权限管理

生产测试分别管理

接口在生产环境的应都为稳定版本，而测试环境的版本会更新，但不代表是稳定版，因此生产与测试的接口文档应分别管理。

如XXX空间下，其生产与测试应创建不同项目以分开管理。

空间

普通空间

普通空间以提供接口的单项目区分，如XXX建立自己的空间，YYY建立自己的空间。

聚合空间

聚合空间以团队为单位聚合，其本身并不管理具体的项目接口，而是用于将其负责的项目的普通空间，聚合在一起，以便于团队内人员找到对应项目。

维护更新接口文档

基于Swagger

如果目前已集成了swagger，可去除对swagger-ui的依赖，添加torna的插件依赖：

pom.xml添加依赖：

<dependency>
    <groupId>cn.torna</groupId>
    <artifactId>swagger-plugin</artifactId>
    <version>最新版本</version>
    <scope>test</scope>
</dependency>

swagger-plugin最新版本：maven
插件的作用是将本地项目中的Swagger文档内容推送到Torna平台，使用平台统一管理项目文档。

使用插件的好处有：

• 不用启动项目即可查看文档，调试接口 可区分多环境调试（开发环境、测试环境）
• 项目中只需要依赖springfox-swagger2即可，springfox-swagger-ui可以移除
• 可定义第三方jar中没有写注解的类

使用步骤：

点击项目列表，创建一个项目，进入项目，创建一个模块

点击创建好的模块，切换到OpenAPI选项卡，得到url，token

src/main/resources下添加一个torna.json文件，内容如下：

  // 开启推送
  "enable": true,
  // 扫描package，多个用;隔开
  "basePackage": "cn.torna.tornaexample.controller",
  // 推送URL，IP端口对应Torna服务器
  "url": "http://localhost:7700/api",
  // 模块token
  "token": "931167d9347e4aec9409f2b275437431",
  // 调试环境，格式：环境名称,调试路径，多个用"|"隔开
  "debugEnv": "test,http://127.0.0.1:8088",
  // 推送人
  "author": "Jim",
  // 打开调试:true/false
  "debug": true,
  // 是否替换文档，true：替换，false：不替换（追加）。默认：true
  "isReplace": true

新增一个测试用例，内容如下：

/** * 推送swagger文档 */
public class DocPushTest 
    public static void main(String[] args) 
        SwaggerPlugin.pushDoc();
    

运行main方法，插件会自动把swagger文档推送到Torna服务器。

扫描特定的接口

如果只想推送某一个controller中的接口，或者只想推送某一个接口，可在配置文件中添加如下配置：

  ...
  "scanApis": [
    // 只推送UserController中的接口
    "com.xxx.UserController"
  ],
  ...        

scanApis是一个数组，可定义多个类，如果只想推送一个接口，填方法全名称即可：

  ...
  "scanApis": [
    // 只推送UserController中的接口
    "com.xxx.UserController",
    // 指定方法全名称，推送某一个接口
    "com.xxx.OrderController.get"
  ],
  ...        

以上配置会推送UserController中所有接口 + OrderController.get接口

TIP

IDEA可以右键方法 -> Copy/Paste Special -> Copy Reference快速复制方法全名称

推送错误码

增加"codes": […, …]节点定义错误码，格式如下：

  ...
  "codes": [
    // 定义错误码
    
      "name": "错误码", // 分组名称
      "description": "这里是全局错误码", // 错误码描述
      "itemType": "string", // 错误码类型
      "items": [ // 错误码列表
         "value": "W_10001", "description": "参数错误" ,
         "value": "W_10002", "description": "缺少token" ,
         "value": 10000, "type": "number", "description": "缺少参数"  // 单独指定类型
      ]
    
  ]
  ...        

此外还可以定义枚举类型：

  // 定义枚举
  "codes": [
    // 定义枚举
    
      "name": "订单状态枚举",
      "itemType": "number",
      "items": [
         "name": "WAIT_PAY", "value": 0, "description": "未支付" ,
         "name": "HAS_PAY", "value": 1, "description": "已支付" ,
         "name": "CANCEL", "value": 2, "description": "取消支付" 
      ]
    ,
    
  ]

codes节点全部参数如下：

  "codes": [
    
      "name": "枚举名称【必填】",
      "description": "描述【可选】",
      "itemType": "枚举类型【可选】",
      "items": [ // 枚举项，必填
         "name": "名称【可选】，不填使用value", "type": "类型【可选】，不填使用itemType", "value": "值【必填】", "description": "描述【可选】" 
      ]
    
  ]

第三方类处理

接口返回第三方类，但是没有写swagger注解，生成的文档没有描述、示例等信息，如mybatis-plus中的Page类。

@ApiOperation(value = "第三方类演示")
@PostMapping("query")
public Result<Page<OrderDetail>> query(@RequestBody OrderQuery query) 
    return Result.ok(new Page<>());

解决方法，在torna.json文件中定义一个jarClass节点，内容如下：

  // 第三方jar中的class配置
  "jarClass": 
    // Page是第三方jar中的类，需要给类中的属性定义文档信息
    "com.baomidou.mybatisplus.extension.plugins.pagination.Page": 
      "records":  "value": "查询数据列表", "example": "" ,
      "total":  "value": "总数", "example": "100" ,
      "size":  "value": "页数", "example": "10" ,
      "current":  "value": "当前页", "example": "1" ,
      "countId":  "hidden": true ,
      "orders":  "hidden": true 
    ,
    "com.xxx.common.Result": 
        "code":  "value": "查询数据列表", "example": "100" ,
        "data":  "value": "数据", "example": "" ,
        "msg":  "value": "错误消息", "example": "xx" 
    
  

其中key为第三方类的全限定名，value是类中字段信息，各个属性值对应@ApiParam中的属性，相当于给records属性加了@ApiParam注解。

多环境配置
默认查找resources下的torna.json，可复制一份，命名为torna-test.json，用来区分不同环境，然后参数传文件名称

SwaggerPlugin.pushDoc("torna-test.json");

注解扩展使用
使用@ApiOperation.extensions的扩展属性用来配置其它信息

指定维护人

指定之后将会在文档页展示当前接口的维护人

@ApiOperation(value = "获取产品", notes = "获取产品说明。。", extensions = 
    // 指定维护人，name固定为author
    @Extension(name = "author", properties = 
        // name：维护人姓名，value空，可以填一个或多个
        @ExtensionProperty(name = "Tom", value = ""),
        @ExtensionProperty(name = "Jim", value = ""),
    )
)

指定接口错误码

指定之后将会在文档页面定义该接口的错误码

@ApiOperation(value = "获取产品", notes = "获取产品说明。。", extensions = 
    // 指定错误码，name固定为code
    @Extension(name = "code", properties = 
        @ExtensionProperty(name = "100001", value = "id错误"),
        @ExtensionProperty(name = "100002", value = "错误描述2"),
        @ExtensionProperty(name = "100003", value = "错误描述3")
    )
)

格式化输出

  // 调试输出json格式化
  "debugPrintFormat": true

指定后，推送的内容将会格式化输出

基于Smart-doc

最小配置单元

在自己的项目中创建一个json配置文件，smart-doc-maven-plugin/smart-doc-gradle-plugin插件会根据这个配置生成项目的接口文档。 例如在项目中创建/src/main/resources/smart-doc.json。配置内容参考如下。

outPath: 指定文档的输出路径,相对路径时请用./开头，

eg:./src/main/resources/static/doc


   "outPath": "D://md2" 

如果你想把html文档也打包到应用中一起访问，则建议你配置路径为：src/main/resources/static/doc
如果是多个模块则放到需要生成文档的模块中。

Maven插件

对于多模块的maven，把smart-doc插件相关配置放到启动模块的pom中。

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下-->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意-->
        <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
        <includes>
            <!--格式为：groupId:artifactId;参考如下-->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

请勿盲目复制上述maven插件的配置项，请先仔细阅读每个配置项的注释，然后根据自己项目情况去配置。 否则可能造成生成文档时无法加载源代码注释。

Use Maven Command

添加好插件和配置文件后可以直接运行Maven命令生成文档。

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
// 生成文档推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

// Apache Dubbo RPC文档
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc

// 生成dubbo接口文档推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

注意： 尤其在window系统下，如果实际使用Maven命令行执行文档生成，可能会出现乱码，因此需要在执行时指定-Dfile.encoding=UTF-8。

Use in IDEA

idea中smart-doc-maven插件使用

如何把文档自动推送到torna

首先是在java的spring项目中集成smart-doc。smart-doc的集成看smart-doc官方的其他文档。其实smart-doc一直的理念都是让使用变的简单。因此要把文档推送到smart-doc也很简单，只需要在smart-doc.json文件中添加几行推送到torna的配置

  "serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://server方便直接在postman直接设置环境变量
  "isStrict": false, //是否开启严格模式
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "projectName": "smart-doc",//配置自己的项目名称
  "appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
  "appKey": "20201216788835306945118208",//torna平台对接appKey，torna 1.11.0版本后不再需要, @since 2.0.9,
  "secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret，torna 1.11.0版本后不再需要，@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna测试环境
  "replace": true,//推送torna时替换旧的文档
  "debugEnvUrl":"http://127.0.0.1",//torna

注意： appKey,appToken,secret如果你不是管理员需要去问管理员了解你推送的项目具体的相关信息。

Torna从1.11.0版本开始，使用smart-doc推送文档数据已经不再需要配置appKey和secret， 仅需要配置appToken即可，因此建议升级Torna版本。

如果你是管理员可以在torna的空间管理中查看。

查看空间里相关项目的token

输入图片说明

推送操作

集成smart-doc并完成推送配置后，就可以使用利用smart-doc的maven或者是gradle插件来直接把文档推送到torna中了。 输入图片说明