Scala项目Akka Http整合Swagger时引用外部Schema报406错误

你的问题核心是Akka路由返回外部YAML文件时，没有设置正确的MIME类型，导致Swagger-UI无法解析该资源。以下是具体解决步骤：

1. 修正Akka静态文件的MIME类型映射 #

406错误的直接原因是test_model.yaml返回的Content-Type为application/octet-stream，而Swagger-UI需要的是application/yaml或application/json。在Akka HTTP路由中为YAML文件添加正确的媒体类型映射：

import akka.http.scaladsl.model.ContentTypes
import akka.http.scaladsl.server.Directives._

// 自定义静态文件路由，指定YAML文件的MIME类型
val docsRoutes = pathPrefix("docs") {
  getFromDirectory(
    directory = "docs",
    resolver = ContentTypeResolver.fromExtension(
      Map(
        "yaml" -> ContentTypes.`application/yaml`,
        "yml" -> ContentTypes.`application/yaml`
      )
    )
  )
}

2. 验证路径与路由匹配 #

确认$ref: './models/test_model.yaml#/components/schemas/Test'的路径逻辑：

• 你的swagger.yml位于docs/目录下，相对路径./models/test_model.yaml对应服务器路径/docs/models/test_model.yaml
• 确保Akka路由能正确匹配该路径返回文件，可直接在浏览器访问该URL，检查响应头的Content-Type是否为application/yaml

3. 排查Swagger库的额外限制 #

如果使用的是swagger-akka-http这类封装库，需确认其是否允许加载外部Schema文件。部分库默认可能限制本地文件引用，可查看库文档开启相关配置，但优先确保MIME类型配置正确——因为内部Schema能正常加载，说明核心解析逻辑无问题，问题集中在外部文件的响应类型上。

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