java swagger解析解决[malformed or unreadable swagger supplied]

原创不易，转载请注明出处：
https://zhangxiaofan.blog.csdn.net/article/details/141498211

如果你想看完整的 利用swagger-parser解析yaml中的api请求类型、注释、接口名，可以参考这篇文章。

【Spring/Java项目】如何利用swagger-parser解析yaml中的api请求类型、注释、接口名等等（含示例代码）-CSDN博客

今天在用swagger的包解析yaml等swagger文件的时候，遇到这类错误：

malformed or unreadable swagger supplied

maven包

        <dependency>
            <groupId>io.swagger.parser.v3</groupId>
            <artifactId>swagger-parser</artifactId>
            <version>2.1.12</version>
        </dependency>

错误信息

malformed or unreadable swagger supplied

报错代码

...
        SwaggerParseResult result = new OpenAPIParser().readContents(data.toString(), null, options);
        OpenAPI openAPI = result.getOpenAPI();
        Paths paths = openAPI.getPaths();
...

具体报错的地方是：

SwaggerParseResult 类，里面的 openAPI对象是null，错误信息如图所示：

 解决方案

如果我们遇到malformed or unreadable swagger supplied 这类报错，一般是我们的swagger格式有问题。

我们解析和读取swagger的yaml等文件，一把有2种方式：

方式一：直接通过文件解析：

SwaggerParseResult result = new OpenAPIParser().readLocation(filePath, null, options);

方式二：通过content内容解析

SwaggerParseResult result = new OpenAPIParser().readContents(data.toString(), null, options);

你可能用文件解析的，没有问题。但是用content内容去解析的时候，就报错了。这个时候，需要你把文件内容全部检查一遍。

例如 swagger-test1.yaml 内容如下：（看着没有问题）

swagger: '2.0'
info:
  title: ping test
  version: '1.0'
host: 'localhost'
basePath: /test
schemes:
  - "https"
tags:
  - name: TestManage
    description: 测试管理
paths:
  /some/ping:
    get:
      tags:
        - TestManage
      operationId: pingGet
      description: 一个测试方法
      parameters:
        - name: i
          in: body
          description: query字段
          required: true
          schema:
            $ref: './swagger/swagger-reference.yaml#/type'
      responses:
        '201':
          description: OK

上述swagger如果用content的方式读取就会报错：malformed or unreadable swagger supplied。

因为 io.swagger.parser.v3 的包，解析的时候，会认为你的格式不对

schema:
  $ref: './swagger/swagger-reference.yaml#/type'

所以要换成引用的写法方式：

  schema:
    $ref: '#swagger/swagger-reference.yaml'

正确的格式应该是：

swagger: '2.0'
info:
  title: ping test
  version: '1.0'
host: 'localhost'
basePath: /test
schemes:
  - "https"
tags:
  - name: TestManage
    description: 测试管理
paths:
  /some/ping:
    get:
      tags:
        - TestManage
      operationId: pingGet
      description: 一个测试方法
      parameters:
        - name: i
          in: body
          description: query字段
          required: true
          schema:
            $ref: '#swagger/swagger-reference.yaml'
      responses:
        '201':
          description: OK

再运行代码就不会报错了。