搭建内网开发环境（七）｜基于RAP2搭建接口管理工具

引言

在上一篇文章中介绍了如何在 nexus 中搭建 npm 私服，并实现通过私服下载和上传 package；本篇文章将介绍如部署 API 管理工具rap2。

RAP2 简介

RAP2 是在 RAP1 基础上重做的新项目，它能给你提供方便的接口文档管理、Mock、导出等功能，包含两个组件(对应两个 Github Repository)。

rap2-delos: 后端数据 API 服务器，基于 Koa + MySQL 点击前往
rap2-dolores: 前端静态资源，基于 React 点击前往

RAP2 部署

安装

官方推荐进行使用 docker-compose 部署，官方提供了 docker-compose 文件，点击前往查看，在系列教程的第一篇文章搭建内网开发环境（一）｜基于docker快速部署开发环境中已经集成完成部署了，这里不再赘述。
继续改造 docker-compose.yml 文件

version: "3.8"

networks:
  env-net:
    driver: bridge
services:
  db:
    image: mysql:latest
    restart: on-failure
    container_name: mysql
    environment:
      - TZ=Asia/Shanghai
      - MYSQL_ROOT_PASSWORD=root
      - INSTALL4J_ADD_VM_PARAMS=-Xms128m -Xmx1024m -XX:MaxDirectMemorySize=512m
      - MYSQL_USER=gitea
      - MYSQL_PASSWORD=gitea
      - MYSQL_DATABASE=gitea
      - MYSQL_USER=rap2
      - MYSQL_PASSWORD=rap2
      - MYSQL_DATABASE=rap2
    ports:
      - "3306:3306"
    networks:
      - env-net
    volumes:
      - /opt/mysql/data/:/var/lib/mysql/
      - /opt/mysql/conf.d/my.cnf:/etc/mysql/my.cnf
    privileged: true
  redis:
    image: redis:latest
    container_name: redis
    restart: on-failure
    ports:
      - "6379:6379"
    command:
      redis-server /etc/redis/redis.conf
    volumes:
      - /opt/redis/data:/data
      - /opt/redis/config/redis.conf:/etc/redis/redis.conf
      - /opt/redis/logs:/logs
    networks:
      - env-net
    privileged: true
# 新增 gitea
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=mysql
      - GITEA__database__HOST=db:3306
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - env-net
    volumes:
      - /opt/gitea/data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    privileged: true
    depends_on:
      - db
# 新增rapteam/rap2-dolores
  dolores:
    image: rapteam/rap2-dolores:latest
    container_name: dolores
    ports:
      # 冒号前可以自定义前端端口号，冒号后不要动
      - 38081:38081
    networks:
      - env-net
  # backend
  delos:
    image: rapteam/rap2-delos:latest
    container_name: delos
    ports:
      - 38080:38080
    environment:
      - SERVE_PORT=38080
      - MYSQL_URL=mysql
      - MYSQL_PORT=3306
      - MYSQL_USERNAME=rap2
      - MYSQL_PASSWD=rap2
      - MYSQL_SCHEMA=rap2
      # redis config
      - REDIS_URL=redis
      - REDIS_PORT=6379
      # production / development
      - NODE_ENV=production
    command: /bin/sh -c 'node dispatch.js'
    networks:
      - env-net
    depends_on:
      - redis
      - db

执行 docker-compose up -d 等待容器启动完成，可通过 docker-compose 查看容器状态

启动后，首次运行需要手动执行初始化数据库脚本，⚠️注意: 只有第一次该这样做
docker-compose exec delos node scripts/init

部署成功后访问，端口号为 docker-compose 中配置的
前端：http://10.0.0.3:28081
后端：http://10.0.0.3:28080

升级

Rap 经常会进行 bugfix 和功能升级，用 Docker 可以很方便地跟随主项目升级

# 拉取一下最新的镜像
docker-compose pull
# 暂停当前应用
docker-compose down
# 重新构建并启动
docker-compose up -d --build
# 有时表结构会发生变化，执行下面命令同步
docker-compose exec delos node scripts/updateSchema
# 清空不被使用的虚悬镜像
docker image prune -f

RAP2 使用

注册账号

创建团队，并添加成员到团队中

创建仓库

添加接口信息
1. 添加模块

添加接口

接口添加完成后可编辑接口的请求头、请求参数和响应内容

右上角可查看接口的编辑历史、移动和导出

安 Apidocx 插件使用

安装 Apidocx 插件

进入 idea 的 settings->plugins,在 Marketplace 中搜索 Apidocx，点击 Install 进行安装

安装完成后，点击 settings -> Other Settings 找到 Apidocx 选择 Rap2（默认是 Yapi），配置 URL 和账号信息
创建 .yapix 文件，.yapix 文件用于配置关联的项目标识
1. 文件名称：.yapix
2. 文件目录：项目模块根目录下
3. 文件格式：properties
4. 文件内容

rap2 获取 projectId http://10.0.0.3:38081/organization/repository/editor?id=16，16 则为 project

Id

右键上传 Apidocx -> Upload To Rap，弹出的信息如果之前有配置直接点击 ok，如果未配置填写相关信息，点击 ok 开始上传

文档生成规则

标准的Javadoc文档就能生成很好的API文档，对于生成文档的准确性有两个建议。

文档注释: 类、方法、字段文档注释应完善
使用实体类: 接收参数、响应参数，避免使用map等类型
| 目标 | 描述 |
| — | — |
| 接口分类 | 文档标记@module(推荐） > 类文档注释第一行 > 文档标记@menu(已废弃) |
| 接口名称 | 方法文档注释第一行(推荐) > 文档标记@description(已废弃） |
| 接口描述 | 方法文档注释描述非第一行 |
| 字段名称 | 字段描述（也兼容swagger） |
| 文档标记 | @ignore 标记的类、方法、字段会被忽略（有侵入性） |

上传 API 到 RAP2

测试上传 API

编写测试接口

编写一个返回版本信息的接口上传到之前创建的 test-demo 模块中

TestController.java

package com.geekyous.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDateTime;

/**
 * 接口测试
 *
 * @module test-demo
 */
@RestController
@RequestMapping("/test")
public class TestController {
    
    
    /**
     * 测试接口
     * 用于返回测试版本信息
     *
     * @return version
     */
    @GetMapping("/version")
    public VersionInfo test() {
    
    
        return VersionInfo.builder().version("v1.0.0").createAt(LocalDateTime.now()).build();
    }
}

VersionInfo.java

package com.geekyous.controller;

import lombok.Builder;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 版本信息
 */
@Data
@Builder
public class VersionInfo {
    
    
    /**
     * 版本号
     */
    private String version;

    /**
     * 创建时间
     */
    private LocalDateTime createAt;
}

查看上传结果