当我把属性 springdoc.swagger-ui.url 改为包含 .yaml 扩展时，例如 /v3/api-docs.yaml，我希望已定义分组的URL也能把它包含在内。

例如，使用以下属性：

springdoc.group-configs[1].group=customer
springdoc.group-configs[1].display-name=Customers
springdoc.group-configs[1].paths-to-match=${app.public}

打开Swagger UI之后，我期望会发出请求去获取 http://localhost:8083/v3/api-docs.yaml/customer。然而，请求却发送到 http://localhost:8083/v3/api-docs/customer，从而产生一个 Unable to render this definition 错误。

当我手动访问 http://localhost:8083/v3/api-docs.yaml/customer 时，API文件会被下载。

为什么尽管在属性中已包含 .yaml 扩展，它仍然没有被添加？这是预期的行为吗？如果是，如何才能将其包含进去？

解决方案

springdoc.swagger-ui.url 属性仅影响主API文档的URL，而不影响分组的URL。

当你通过 springdoc.group-configs 定义分组时，springdoc会基于 springdoc.api-docs.path 生成分组的URL（默认为 /v3/api-docs），只是把分组名作为查询参数追加到URL上，如 /v3/api-docs/customer。它并不会从你在swagger-ui.url设置中获取 .yaml 扩展。

如果你也想让分组使用YAML，可以显式地定义这些URL，而不是使用group-configs：

springdoc.swagger-ui.urls[0].url=/v3/api-docs.yaml/customer
springdoc.swagger-ui.urls[0].name=Customers

或你也可以全局设置api-docs路径以使用YAML：

springdoc.api-docs.path=/v3/api-docs.yaml

说实话，我宁愿坚持使用swagger-ui的默认JSON端点，只有在确实需要YAML文件时（比如代码生成或导入到Postman）才使用YAML URL。Swagger UI无论哪种方式都能正常工作，它都能很好地解析这两种格式。