使用OpenAPI生成API遇问题：Postman请求返回HTML而非JSON/YAML

以下是针对该问题的排查和解决步骤：

1. 确认访问正确的API文档端点 #

springdoc-openapi提供了专门的端点用于获取JSON/YAML格式的API定义，而非Swagger UI的HTML页面：

• 获取JSON格式：请求 GET /v3/api-docs
• 获取YAML格式：请求 GET /v3/api-docs.yaml
  若你访问的是/swagger-ui.html，返回Swagger UI的HTML界面属于正常现象。

2. 检查Postman的请求头设置 #

在Postman中，确保请求的Accept头与预期格式匹配：

• 要JSON：设置Accept: application/json
• 要YAML：设置Accept: application/yaml
  如果Accept头包含text/html，服务会优先返回HTML内容。

3. 匹配Spring Boot与springdoc版本 #

springdoc版本和Spring Boot版本强绑定，版本不匹配会引发异常：

• 若使用Spring Boot 2.x，请使用springdoc-openapi-ui 1.6.x版本（如你最初用的1.6.14）
• 若使用Spring Boot 3.x，则必须使用springdoc-openapi-ui 2.x版本（如2.5.0）
  版本不兼容可能导致API文档端点无法正常返回JSON/YAML，转而返回错误页面的HTML。

4. 排查自定义配置是否覆盖端点 #

检查application.properties或application.yaml中是否有修改springdoc端点的配置：

# 示例：自定义API文档路径
springdoc.api-docs.path=/my-api-docs

如果有，需要访问你配置的自定义路径，而非默认的/v3/api-docs。

5. 检查请求映射冲突 #

确认你的Controller中没有定义与API文档端点（如/v3/api-docs）相同的请求映射，否则会优先匹配Controller的处理逻辑，返回非预期的HTML内容。

内容的提问来源于stack exchange，提问作者Abinash Khattri