ChatGPT生成接口文档实践案例（1）

图书连载

生成接口文档的方法有很多，如研发人员手工编写或通过Swagger、Postman、ChatGPT自动生成。在此仅针对利用ChatGPT生成接口文档的方法进行介绍，其他两种方法不赘述。

以飞机订票系统的用户注册功能为例，其用户注册的界面如图5-9所示。

图5-9 用户注册的界面

(1) 准备关键信息

在本案例中，笔者准备的接口关键信息如下所示。

接口名称：用户注册接口

接口描述：新用户注册接口，注册内容包括：用户名、姓名、地址、邮编等。

请求地址：http://127.0.0.1:1080/cgi-bin/login.pl

请求方式：POST

请求体参数：

username 必填 用户名

password 必填 密码

passwordConfirm 必填 确认密码

firstName 选填 名字

lastName 选填 姓氏

address1 选填 街道地址

address2 选填 城市邮编

register.x 选填 注册x坐标

register.y 选填 注册y坐标

响应示例：HTML格式页面，注册成功 显示 Thank you， <b>{username}</b>

(2) ChatGPT生成接口文档

关键信息输入完成以后，就可以让ChatGPT生成用户接口文档，如图5-10所示。

图5-10 ChatGPT生成的用户注册接口文档

ChatGPT给出两个方案供我们选择，即Response 1和Response 2，分别如图5-11和图5-12所示。

图5-11 ChatGPT生成的Response 1接口文档（部分）

以下内容为ChatGPT生成的Response 1接口文档。

ChatGPT生成的Response 1接口文档

以下是飞机订票系统的用户注册接口文档：

用户注册接口

接口描述： 新用户注册接口，允许用户提供以下信息进行注册：用户名、密码、确认密码、名字、姓氏、街道地址、城市邮编。

请求地址： http://127.0.0.1:1080/cgi-bin/login.pl

请求方式： POST

请求体参数：

请求示例：

POST http://127.0.0.1:1080/cgi-bin/login.pl

Body:

{

"username": "sample_user"，

"password": "password123"，

"passwordConfirm": "password123"，

"firstName": "John"，

"lastName": "Doe"，

"address1": "123 Main St"，

"address2": "City， Zip Code"，

"register.x": "100"，

"register.y": "200"

}

响应示例：

如果注册成功，服务器将返回一个HTML格式的页面，显示以下内容：

Thank you， <b>sample_user</b>

如果注册失败，服务器应该返回相应的错误信息，例如用户名已被占用或密码不匹配等信息。

图5-12 ChatGPT生成的Response 2接口文档（部分）

以下内容为ChatGPT生成的Response 2接口文档。

ChatGPT生成的Response 2接口文档

以下是用户注册接口的接口文档：

用户注册接口

接口描述

新用户注册接口，用户可以通过此接口进行注册。注册信息包括用户名、密码、确认密码、名字、姓氏、街道地址和城市邮编等。

请求地址

POST http://127.0.0.1:1080/cgi-bin/login.pl

请求方式

POST

请求体参数

响应示例

注册成功后，服务器将返回一个HTML格式的页面，显示感谢消息，其中{username}将被替换为实际注册的用户名。

Thank you， <b>{username}</b>

错误响应示例

如果注册过程中发生错误，服务器可能返回相应的错误信息，如用户名已存在、密码不匹配等。

Registration failed. Please check your input and try again.

这是用户注册接口的接口文档，您可以使用这些信息来设计和实现相应的功能。希望这对您有所帮助！

不难发现，两个方案都出色地完成了接口文档的生成，但笔者更喜欢Response 2的表达，因为其描述更加全面。