API开源免费接口管理

Posted 2022-11-07 zero13_小葵司

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了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中了。输入图片说明

以上是关于API开源免费接口管理的主要内容，如果未能解决你的问题，请参考以下文章

API开源免费接口管理

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

DOClever接口管理平台都有哪些优势?

Elasticvue - 用于浏览器的免费开源 Elasticsearch GUI

百度地图的api接口可以免费随意调用吗