ChatGPT生成接口文档实践案例（二）
不难发现，两个方案都出色地完成了接口文档的生成，但笔者更喜欢Response 2的表达，因为其描述更加全面。
还可以让ChatGPT生成符合OpenAPI 3.0规范的接口文档，以便于项目相关成员阅读，如图5-13所示。
为什么要生成OpenAPI 3.0规范的接口文档呢？下面简单介绍一下OpenAPI 3.0。OpenAPI 3.0（又称为OpenAPI Specification 3.0或OAS 3.0）是一种规范，专门用于描述RESTful API（Application Programming Interface，应用程序接口）。它是OpenAPI 2.0（之前称为Swagger）的升级版。OpenAPI 3.0的目标是提供更丰富的API文档和规范，以便开发人员更好地理解和使用API。这一规范采用JSON（JavaScript Object Notation，JS对象简谱）或YAML（YAML Ain't a Markup Language，YAML不是标记语言）格式，因此易于阅读和编写。开发人员可以利用各种工具生成API文档，以更轻松地构建和维护API文档。这有助于提高API的可互操作性，促进不同开发团队之间的合作。
图5-13 ChatGPT生成的符合OpenAPI 3.0规范的接口文档（部分）
ChatGPT生成的符合OpenAPI 3.0规范的接口文档如下所示。
ChatGPT生成的符合OpenAPI 3.0规范的接口文档
以下是用户注册接口的 OpenAPI 3.0.0 格式文档：
openapi: 3.0.0
info:
title: 飞机订票系统
description: 飞机订票系统用户注册接口文档
version: 1.0.0
paths:
/cgi-bin/login.pl:
post:
summary: 新用户注册接口
description: 新用户注册接口，用户可以通过此接口进行注册。注册信息包括用户名、密码、确认密码、名字、姓氏、街道地址和城市邮编等。
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
type: string
description: 用户名
password:
type: string
description: 密码
passwordConfirm:
type: string
description: 确认密码
firstName:
type: string
description: 名字
lastName:
type: string
description: 姓氏
address1:
type: string
description: 街道地址
address2:
type: string
description: 城市邮编
register.x:
type: number
description: 注册x坐标
register.y:
type: number
description: 注册y坐标
responses:
'200':
description: 注册成功
content:
text/html:
schema:
type: string
example: 'Thank you， <b>{username}</b>'
'400':
description: 注册失败
content:
text/html:
schema:
type: string
example: 'Registration failed. Please check your input and try again'
这是 OpenAPI 3.0.0 格式的用户注册接口文档，您可以将其用于API文档工具或生成可视化文档以方便阅读和理解。希望这对您有所帮助！
ChatGPT很快就生成了符合OpenAPI 3.0规范的关于飞机订票系统的用户注册接口文档，它还告诉我们该如何使用这段YAML格式的代码，是不是非常贴心？将这段代码复制到Swagger Editor中，可以正常显示，如图5-14所示。
图5-14 Swagger Editor中显示用户注册接口文档
可以按照前面笔者提供的方法继续生成其他接口文档，这里不赘述。
无论使用哪种编程语言和开发框架，生成符合Swagger或OpenAPI 3.0规范的接口文档的关键都在于选择合适的工具和注解来描述API。
接口文档的生成过程并不是最重要的，最重要的是确保生成的接口文档内容准确无误、简明清晰，能够让项目相关人员容易理解。在实际工作中，研发人员有时可能会修改API的代码，这可能导致接口参数、返回值等内容发生变化。在这种情况下，研发人员应该及时更新相关接口文档，以确保其准确性。
一些企业可能存在没有接口文档的情况，这会给测试人员的接口测试工作带来困难。测试人员不仅需要分析接口的输入和输出，还需要负责编写接口文档，这容易导致漏测情况的发生。因此，笔者建议接口文档的编写和维护工作由研发人员来负责，特别是在有了ChatGPT的辅助之后。有一些企业还开发了一些工具或平台，通过调用OpenAI提供的相关API来自动生成接口文档并发布，这极大地提高了研发及测试的效率。
- 进行多轮提问修正
事实上，我们在使用ChatGPT生成接口文档时可能不会“一气呵成”，有时可能需要同ChatGPT进行多轮会话，才能生成最终的接口文档。在操作时我们可以根据实际情况来调整ChatGPT的提示词，提供更多的细节信息，例如参数的数据类型、取值范围、输入示例等，从而获得满意的接口文档。