1. 原始openapi specification
openapi: 3.0.1 info: title: 小助手 description: 根据用户输入信息，进行测试 version: "v2" servers: - url: https://aaa.bbb.com/api/forward components: responses: UError: description: Bearer token缺失或无效 content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: "接口权限校验失败" SunError: description: 业务异常 content: application/json: schema: type: object properties: code: type: integer example: 0 message: type: string example: "业务异常" paths: /forward: post: operationId: aaa summary: 根据用户输入信息，进行测试 requestBody: required: true content: application/json: schema: type: object required: [server_flag, server_dir, params] properties: server_flag: type: string description: descaaabbbccc example: "testddd" server_dir: type: string description: descddd example: "Aaaa.bbbb" params: type: object description: 第三方所需参数 properties: clntManagerId: type: string description: col1 example: "0d06099fed39eb683782fa104dd33998" cumerName: type: string description: col2 example: "xxx" cumerPhone： type: string description: col3 example: "123123123" dlerCode: type: string description: col4 example: "8f52d344eab7fec87e1bb168898ba494" proctSeries: type: string description: col5 example: "D" rerveTime: type: string description: col6 example: "2024-06-21 15:30" responses: "200": description: 成功 content: application/json: schema: type: object required: [code, message, data] properties: code: type: integer example: 200 message: type: string example: "ok" data: type: object properties: CODE: type: integer example: 200 DATA: type: object properties: eventId: type: string example: "062e0xxx71a1dde" eventId: type: string example: "cdce6xxx13123" RESULT: type: string example: "" '401': $ref: '#/path1/path2/U1Error' '0': $ref: '#/path1/path2/SuError'
2. 报错
INVALID PARAMETER: apiScheme definition is invalid
3. 排查过程
参考文档排查具体报错：https://editor.swagger.io/
- 右侧有这个配置文件具体的报错情况，点击具体报错可以跳转到具体行。第一个可以明显看出74行有个中文冒号，key的颜色都没有匹配上，改成英文冒号后正常
- 修改后可以看到第二个报错，点击跳转后可以到具体报错的地方，这里是仅支持三位的状态码，配置文件中有个状态码是“0”，改成“400”后正常
- 继续修改后可以看到后面的报错，如下路径（可以直接点击跳转到DATA）下，有个名为“eventId”的额外的配置项是不被允许的，仔细看发现配置在properties里面的eventId应该是粘贴重复且层级错误了，去掉后正常。
- 具体状态码的ref需要时文件中已经配置合法的location，这里需要改成对应的如：'#/components/responses/UError'
4. 修改后的openapi specification
openapi: 3.0.1 info: title: 小助手 description: 根据用户输入信息，进行测试 version: "v2" servers: - url: https://aaa.bbb.com/api/forward components: # securitySchemes: # BearerAuth: # type: http # scheme: bearer # bearerFormat: JWT responses: UError: description: Bearer token缺失或无效 content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: "接口权限校验失败" SunError: description: 业务异常 content: application/json: schema: type: object properties: code: type: integer example: 0 message: type: string example: "业务异常" paths: /forward: post: operationId: aaa summary: 根据用户输入信息，进行测试 requestBody: required: true content: application/json: schema: type: object required: [server_flag, server_dir, params] properties: server_flag: type: string description: descaaabbbccc example: "testddd" server_dir: type: string description: descddd example: "Aaaa.bbbb" params: type: object description: 第三方所需参数 properties: clntManagerId: type: string description: col1 example: "0d06099fed39eb683782fa104dd33998" cumerName: type: string description: col2 example: "xxx" cumerPhone: type: string description: col3 example: "123123123" dlerCode: type: string description: col4 example: "8f52d344eab7fec87e1bb168898ba494" proctSeries: type: string description: col5 example: "D" rerveTime: type: string description: col6 example: "2024-06-21 15:30" responses: "200": description: 成功 content: application/json: schema: type: object required: [code, message, data] properties: code: type: integer example: 200 message: type: string example: "ok" data: type: object properties: CODE: type: integer example: 200 DATA: type: object properties: eventId: type: string example: "062e0xxx71a1dde" RESULT: type: string example: "" '401': $ref: '#/components/responses/UError' '400': $ref: '#/components/responses/SunError'
