Scalatra API 文档自动生成：Swagger 集成完整教程

Scalatra 作为一款轻量级高性能的 Scala Web 框架，提供了与 Swagger 的无缝集成能力，帮助开发者自动生成专业的 API 文档。本文将详细介绍如何在 Scalatra 项目中集成 Swagger，实现 API 文档的自动生成与管理，让你的 API 开发更高效、文档更规范。## 为什么选择 Scalatra + SwaggerSwagger 是目前最流行的 API 文档

孙樱晶Red

599人浏览 · 2026-04-07 07:02:21

孙樱晶Red · 2026-04-07 07:02:21 发布

Scalatra API 文档自动生成：Swagger 集成完整教程

【免费下载链接】scalatra Tiny Scala high-performance, async web framework, inspired by Sinatra 项目地址: https://gitcode.com/gh_mirrors/sc/scalatra

Scalatra 作为一款轻量级高性能的 Scala Web 框架，提供了与 Swagger 的无缝集成能力，帮助开发者自动生成专业的 API 文档。本文将详细介绍如何在 Scalatra 项目中集成 Swagger，实现 API 文档的自动生成与管理，让你的 API 开发更高效、文档更规范。

为什么选择 Scalatra + Swagger

Swagger 是目前最流行的 API 文档生成工具之一，它允许开发者通过代码注解的方式定义 API 规范，自动生成交互式文档。在 Scalatra 项目中集成 Swagger 具有以下优势：

减少重复劳动：通过代码注解自动生成文档，避免手动编写和维护文档的繁琐工作
保持文档与代码同步：API 变更时只需更新代码注解，文档自动更新
提升开发效率：提供交互式文档界面，方便测试和调试 API
标准化 API 设计：遵循 OpenAPI 规范，使 API 设计更加规范和专业

集成准备：添加 Swagger 依赖

要在 Scalatra 项目中使用 Swagger，首先需要添加相关依赖。Scalatra 提供了专门的 Swagger 支持模块，你可以在项目的构建文件中添加以下依赖：

// 在 build.sbt 中添加 Swagger 依赖
libraryDependencies += "org.scalatra" %% "scalatra-swagger" % "2.5.1"

基础集成：启用 Swagger 支持

Scalatra 提供了 SwaggerSupport 特质，通过混入该特质可以快速为你的 Scalatra 应用添加 Swagger 支持。以下是基本的集成步骤：

1. 创建 Swagger 实例

首先，你需要创建一个 Swagger 实例，用于配置 API 的基本信息：

import org.scalatra.swagger._

val swagger = new Swagger(
  apiInfo = ApiInfo(
    title = "My Scalatra API",
    description = "A sample API built with Scalatra and Swagger",
    version = "1.0.0",
    termsOfServiceUrl = Some("http://example.com/terms"),
    contact = Some("contact@example.com"),
    license = Some("MIT"),
    licenseUrl = Some("http://example.com/license")
  )
)

2. 混入 SwaggerSupport 特质

在你的 Scalatra Servlet 中混入 SwaggerSupport 特质，并将 Swagger 实例传递给它：

class MyApiServlet(implicit val swagger: Swagger) extends ScalatraServlet with SwaggerSupport {
  // API 路由定义...
}

文档注解：定义 API 规范

Swagger 通过注解来定义 API 规范。Scalatra 提供了丰富的注解支持，让你可以轻松描述 API 的各个方面。

基本 API 注解

使用 @Api 注解来描述整个 API 资源：

@Api(
  value = "/users",
  description = "User management API",
  produces = "application/json"
)
class UserApi(implicit val swagger: Swagger) extends ScalatraServlet with SwaggerSupport {
  // API 方法定义...
}

方法级注解

使用 @ApiOperation 注解来描述具体的 API 方法：

@ApiOperation(
  httpMethod = "GET",
  path = "/users/{id}",
  summary = "Get user by ID",
  notes = "Returns a single user based on their ID",
  response = classOf[User]
)
get("/users/:id") {
  // 处理逻辑...
}

参数注解

使用 @ApiParam 注解来描述 API 参数：

@ApiOperation(
  httpMethod = "GET",
  path = "/users/{id}",
  summary = "Get user by ID"
)
@ApiParams(Array(
  new ApiParam(
    name = "id",
    value = "User ID",
    required = true,
    dataType = "Long",
    paramType = "path"
  )
))
get("/users/:id") {
  val id = params("id").toLong
  // 处理逻辑...
}

模型注解

使用 @ApiModel 和 @ApiModelProperty 注解来描述数据模型：

@ApiModel(description = "A user representation")
case class User(
  @ApiModelProperty(value = "User ID", required = true)
  id: Long,
  
  @ApiModelProperty(value = "User name", required = true, example = "John Doe")
  name: String,
  
  @ApiModelProperty(value = "User email", required = true, dataType = "string", format = "email")
  email: String
)

高级配置：自定义 Swagger UI

Scalatra Swagger 集成默认提供了 Swagger UI 界面，你可以通过以下配置来自定义其行为：

配置 Swagger UI 路径

你可以通过重写 swaggerUiPath 方法来自定义 Swagger UI 的访问路径：

override def swaggerUiPath: String = "api-docs"

启用 CORS 支持

为了允许 Swagger UI 跨域访问你的 API，需要启用 CORS 支持：

class MyApiServlet(implicit val swagger: Swagger) extends ScalatraServlet with SwaggerSupport with CorsSupport {
  // 配置 CORS...
  options("/*") {
    response.setHeader("Access-Control-Allow-Headers", request.getHeader("Access-Control-Request-Headers"))
  }
}

实际示例：完整的 Swagger 集成

以下是一个完整的 Scalatra + Swagger 集成示例，展示了如何创建一个简单的用户 API 并生成 Swagger 文档：

import org.scalatra._
import org.scalatra.swagger._
import org.json4s.JsonDSL._
import org.json4s.jackson.JsonMethods._

// 定义数据模型
@ApiModel(description = "A user representation")
case class User(
  @ApiModelProperty(value = "User ID", required = true)
  id: Long,
  
  @ApiModelProperty(value = "User name", required = true, example = "John Doe")
  name: String,
  
  @ApiModelProperty(value = "User email", required = true, dataType = "string", format = "email")
  email: String
)

// 创建 Swagger 实例
val swagger = new Swagger(
  apiInfo = ApiInfo(
    title = "User API",
    description = "A simple API for user management",
    version = "1.0.0"
  )
)

// 定义 API Servlet
@Api(
  value = "/users",
  description = "User management operations"
)
class UserApi(implicit val swagger: Swagger) extends ScalatraServlet with SwaggerSupport with NativeJsonSupport {
  
  // 获取所有用户
  @ApiOperation(
    httpMethod = "GET",
    path = "/users",
    summary = "Get all users",
    response = classOf[List[User]]
  )
  get("/users") {
    // 实际应用中这里会从数据库获取数据
    List(
      User(1, "John Doe", "john@example.com"),
      User(2, "Jane Smith", "jane@example.com")
    )
  }
  
  // 获取单个用户
  @ApiOperation(
    httpMethod = "GET",
    path = "/users/{id}",
    summary = "Get user by ID",
    response = classOf[User]
  )
  @ApiParams(Array(
    new ApiParam(
      name = "id",
      value = "User ID",
      required = true,
      dataType = "Long",
      paramType = "path"
    )
  ))
  get("/users/:id") {
    val id = params("id").toLong
    // 实际应用中这里会从数据库获取数据
    User(id, "John Doe", "john@example.com")
  }
}