如何通过Swagger在Linux上进行API错误诊断

在Linux系统上使用Swagger进行API错误诊断，可以按照以下步骤进行：

安装Swagger

• 使用npm安装Swagger命令行工具（如果你使用的是Node.js）：

  npm install -g swagger
  

• 使用Docker安装Swagger Editor（推荐初学者或无图形界面需求的情况）：

  • 拉取Swagger Editor的Docker镜像：

    docker pull SwaggerEditor/Swagger-Editor
    

  • 运行容器并将容器的8080端口映射到宿主机的8080端口：

    docker run -p 8080:8080 SwaggerEditor/Swagger-Editor
    

  • 完成后，你可以在浏览器中通过访问 http://localhost:8080 来使用Swagger Editor。

配置Swagger

• 进入项目目录，并编辑Swagger配置文件（通常是 swagger.yaml 或 swagger.json）。这个文件包含了API的基本信息、端点、参数、请求和响应等配置。

• 启动Swagger，配置完成后，通过命令行启动Swagger。启动后会在浏览器中打开一个界面，显示你的API文档。

测试接口

• 在Swagger UI界面中，你可以点击“TRY IT OUT”按钮来测试API请求。输入必要的参数，然后发送请求并查看返回结果。这对于开发和调试API非常有用。

常见问题及解决办法

• 异常描述：No enum constant org.springframework.web.bind.annotation.RequestMethod.Get

  • 原因：根据异常栈，能看出是springfox-swagger-common执行OperationHttpMethodReader.apply()方法是抛出来的，分析日志 RequestMethod.Get 没有对应的enum，通过检查Controller中RequestMethod，发现了问题所在：枚举类中method方法都是大写，而我的代码中将method写成了小写，导致了在获取enum类型的时候，匹配不上抛出异常。
  • 解决办法：将httpMethod “Get” 改成 “GET” 即可。

• 异常描述：java.lang.NumberFormatException: For input string:“”

  • 原因：看日志，swagger-models这个包中的AbstractSerializableParameter.getExample()方法的时候出现异常了，此外还有一条WARN日志，Illegal DefaultValue null for parameter type integer，意思是：有个默认值是空字符串的变量转换成Integer类型时异常。

  • 解决办法：分析了下maven的包依赖：发现swagger-models的版本为1.5.20，果断去mvnrepository上去寻找有没有新的包修复过这个bug：发现最新的版本1.6.2，果断换成最新版本：

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <exclusions>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.6.2</version>
    </dependency>
    

通过以上步骤，你可以在Linux系统上使用Swagger来测试和诊断你的API接口。Swagger不仅提供了一个可视化的界面来展示API文档，还允许用户直接与API进行交互，进行实时测试，从而大大提高了开发和调试的效率。