|
不难发现，两个方案都出色地完成了接口文档的生成，但笔者更喜好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的提示词，提供更多的细节信息，例如参数的数据范例、取值范围、输入示例等，从而获得满意的接口文档。
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。 | 
