从0到1的yapi接口文档部署记录

@
目录

概要
skills结合ai生成文档
Yapi部署
小结

概要

最近我那管理后台来活了，之前都是我一个人搞，不用写接口文档，现在后端的事太多了，前端给安卓同事来写了，我这边就只负责后端，但是他们要接口文档，特意调研了一番,

问了ai我这情况该如何选择，ai给了我三个选择，

继续用ai生成，但是太笨了
使用yapi之类的第三方生成接口文档
使用原生的 SpringDoc 生成 JSON

一开始看了showdoc，对比感觉没有可以参考注释直接生成接口文档的，他只是通过参数来判断,对比了下最终选择了yapi，他主要优点是代码几乎无侵入，部署简单，方便管理，而且上家公司就是用的这个，那就这个吧

skills结合ai生成文档

顺便记录下使用一开始我想的是就用ai生成文档，还特意总结了skills方便后面使用，总结如下

复制代码

---
name: Generate API Document For Controller
description: 根据Controller生成详细的接口文档，包含请求方式、入参解释、返回示例及返回字段详尽解释。
---

# Generate API Document For Controller

当你被要求为 Controller 或指定接口整理接口文档时，请严格按照以下结构和要求输出：

1. **接口基本信息**：
   - 接口名称
   - 接口路径 (Endpoint)
   - 请求方式 (GET/POST)
   - 请求体格式 (如 application/json, form-data, url parameters)

2. **入参说明 (请求参数)**：
   - 以表格形式列出所有请求参数。
   - 包含字段：参数名、数据类型、是否必填。
   - **必填要求**：每个字段必须有**详细的含义解释**（根据实体类或AO的注释/上下文推理）。
   - **核心要求**：如果是 POST/PUT 等包含 Request Body 的请求，必须单独提供一份具有代表性的 JSON **请求体示例**(Request Body Example)。

3. **返回数据说明 (响应参数)**：
   - 提供一个完整的、具有代表性的 JSON 返回格式样例 (必须包含系统基础外层结构，如 `code`, `msg`, `data`)。
   - **核心要求（强限制）**：以表格形式逐一解释返回的 JSON （尤其是 `data` 对象内部）中的每一个字段含义和数据类型。不可省略字段解释！

4. **输出格式**：
   - 必须使用标准的 Markdown 语法（多用表格和代码块）。
   - 全程使用中文（遵循全局指令要求）。

但是这一套每次都需要花费老长时间去生成，而且如果我有改动又要重新生成，再粘贴到在线文档，太麻烦了，最终决定使用别的第三方。

Yapi部署

首先推荐使用docker-compose的方式安装，方便追溯管理，docker-compose.yml的内容如下

复制代码

ersion: '3'

services:
  yapi-web:
    image: jayfong/yapi:latest
    container_name: yapi-web
    restart: unless-stopped
    ports:
      - "40001:3000"  # 访问地址: http://localhost:40001
    environment:
      - YAPI_ADMIN_ACCOUNT=wutao@chimeta.com    # 管理员邮箱
      - YAPI_ADMIN_PASSWORD=111111 # 管理员密码（请修改！）
      - YAPI_CLOSE_REGISTER=true               # 关闭注册（安全）
      - YAPI_DB_SERVERNAME=yapi-mongo          # MongoDB 服务名
      - YAPI_DB_PORT=27017
      - YAPI_DB_DATABASE=yapi                  # 数据库名
      - YAPI_MAIL_ENABLE=false
    depends_on:
      - yapi-mongo
    volumes:
      - ./logs:/home/yapi/logs                # 日志持久化

  yapi-mongo:
    image: mongo:4.4
    container_name: yapi-mongo
    restart: unless-stopped
    volumes:
      - ./data/db:/data/db                    # 数据持久化
    command: [--bind_ip_all]

然后执行docker compose up -d，没有报错后用docker ps查看运行状态

然后去阿里云开放端口号，然后IP+端口号浏览器进入，使用账号和密码登录进去，再新建个项目

然后进入路径：你的项目-设置-token配置-复制token

接着去idea里面安装插件"easyYapi"

装好后再在路径：setting-other settings-Yapi 里面粘贴你的后台yapi的url，如下截图

回到代码界面找到个controller，右击选择yapi-

第一次会让你填入token，就是刚刚叫你复制的token粘贴进去，然后点确认，这个controller里面的接口就生成上去了，如图所示

小结

ai很多时候都能给我们比较文档化的优秀建议，但有些必须要手操和经历才能实现你的项目需求，还是需要带着脑子利用ai加自己的思考去做事才行