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

@
目录

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

概要

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

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

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

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

1. ---
2. name: Generate API Document For Controller
3. description: 根据Controller生成详细的接口文档，包含请求方式、入参解释、返回示例及返回字段详尽解释。
4. ---
6. # Generate API Document For Controller
8. 当你被要求为 Controller 或指定接口整理接口文档时，请严格按照以下结构和要求输出：
10. 1. **接口基本信息**：
11.    - 接口名称
12.    - 接口路径 (Endpoint)
13.    - 请求方式 (GET/POST)
14.    - 请求体格式 (如 application/json, form-data, url parameters)
16. 2. **入参说明 (请求参数)**：
17.    - 以表格形式列出所有请求参数。
18.    - 包含字段：参数名、数据类型、是否必填。
19.    - **必填要求**：每个字段必须有**详细的含义解释**（根据实体类或AO的注释/上下文推理）。
20.    - **核心要求**：如果是 POST/PUT 等包含 Request Body 的请求，必须单独提供一份具有代表性的 JSON **请求体示例**(Request Body Example)。
22. 3. **返回数据说明 (响应参数)**：
23.    - 提供一个完整的、具有代表性的 JSON 返回格式样例 (必须包含系统基础外层结构，如 `code`, `msg`, `data`)。
24.    - **核心要求（强限制）**：以表格形式逐一解释返回的 JSON （尤其是 `data` 对象内部）中的每一个字段含义和数据类型。不可省略字段解释！
26. 4. **输出格式**：
27.    - 必须使用标准的 Markdown 语法（多用表格和代码块）。
28.    - 全程使用中文（遵循全局指令要求）。

复制代码

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

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

1. ersion: '3'
3. services:
4.   yapi-web:
5.     image: jayfong/yapi:latest
6.     container_name: yapi-web
7.     restart: unless-stopped
8.     ports:
9.       - "40001:3000"  # 访问地址: http://localhost:40001
10.     environment:
11.       - YAPI_ADMIN_ACCOUNT=wutao@chimeta.com    # 管理员邮箱
12.       - YAPI_ADMIN_PASSWORD=111111 # 管理员密码（请修改！）
13.       - YAPI_CLOSE_REGISTER=true               # 关闭注册（安全）
14.       - YAPI_DB_SERVERNAME=yapi-mongo          # MongoDB 服务名
15.       - YAPI_DB_PORT=27017
16.       - YAPI_DB_DATABASE=yapi                  # 数据库名
17.       - YAPI_MAIL_ENABLE=false
18.     depends_on:
19.       - yapi-mongo
20.     volumes:
21.       - ./logs:/home/yapi/logs                # 日志持久化
23.   yapi-mongo:
24.     image: mongo:4.4
25.     container_name: yapi-mongo
26.     restart: unless-stopped
27.     volumes:
28.       - ./data/db:/data/db                    # 数据持久化
29.     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里面的接口就生成上去了，如图所示

快捷键：shift+alt+e

小结

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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！