使用するライブラリ

今回はswagger-akka-http/swagger-akka-httpを使用します。

github.com

サンプルプロジェクトがあるのでそちらで解説を入れていきます。

github.com

build.sbtへライブラリ追加

build.sbtに以下を追加します。

libraryDependencies ++= Seq(
  "javax.ws.rs" % "javax.ws.rs-api" % "2.0.1", 
  "com.github.swagger-akka-http" %% "swagger-akka-http" % "2.0.4", 
  "com.github.swagger-akka-http" %% "swagger-scala-module" % "2.0.5",
  "com.fasterxml.jackson.module" %% "jackson-module-scala" % jacksonVersion,
  "io.swagger.core.v3" % "swagger-core" % swaggerVersion,
  "io.swagger.core.v3" % "swagger-annotations" % swaggerVersion,
  "io.swagger.core.v3" % "swagger-models" % swaggerVersion,
  "io.swagger.core.v3" % "swagger-jaxrs2" % swaggerVersion,
  "com.typesafe.akka" %% "akka-http" % akkaHttpVersion,
  ...
)

Swagger Spec生成に必要なライブラリは以下です。
javax.ws.rs-api → サンプルではリクエストメソッドの指定で使用します。
com.github.swagger-akka-http %% swagger-xxx → Swagger Specを生成するライブラリセットです。
io.swagger.core.v3 % swagger-xxx → Swaggerアノテーションを使用するためのライブラリセットです。

ルート定義とSwagger Spec情報定義

まずはAPIの定義から入ります。
参考コードはHelloService.scalaからの抜粋ですが、一部修正を入れています。

　// 44行目から  
  // アノテーション定義がSwagger Spec生成の情報定義になります。
  @Path("/hello/{name}")
  @GET
  @Operation(summary = "Return Hello greeting", description = "Return Hello greeting for named user",
    parameters = Array(new Parameter(name = "name", in = ParameterIn.PATH, description = "user name")),
    responses = Array(
      new ApiResponse(responseCode = "200", description = "Hello response",
        content = Array(new Content(schema = new Schema(implementation = classOf[Greeting])))),
      new ApiResponse(responseCode = "500", description = "Internal server error"))
  )
  // 以下はルート定義
  def getHelloSegment =
    path("hello" / Segment) { name =>
      get {
        complete { (hello ? Hello(name)).mapTo[Greeting] }
      }
    }

結果が先に来てしまうのですが、上記定義で生成されるSwagger Specの定義が以下になります。

  /hello/{name}:
    get:
      summary: Return Hello greeting
      description: Return Hello greeting for named user
      operationId: getHelloSegment
      parameters:
      - name: name
        in: path
        description: user name
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Hello response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Greeting'
        "500":
          description: Internal server error

Swagger SpecのAPI定義に当たる箇所はすべてアノテーションで定義します。
一見、アノテーション定義は複雑に見えますが、Swagger Specを記述されたことがある方はどのアノテーション定義がSwagger Spec上の記述となるか簡単に紐づくと思います。Swagger Specが初見の方は一度Swagger Specの理解から入られるとアノテーションの理解が早まると思います。

Swagger Spec生成サービスの追加

swagger-akka-httpでは、リクエストに対してSwagger Specを返却する仕組みとなているため、Swagger Sepcを生成するサービス作成とルート追加が必要となります。

SwaggerDocService.scala

object SwaggerDocService extends SwaggerHttpService {
  override val apiClasses = Set(classOf[AddService], classOf[AddOptionService], classOf[HelloService], EchoEnumService.getClass)
  override val host = "localhost:12345"
  override val info = Info(version = "1.0")
  override val externalDocs = Some(new ExternalDocumentation().description("Core Docs").url("http://acme.com/docs"))
  //override val securitySchemeDefinitions = Map("basicAuth" -> new BasicAuthDefinition())
  override val unwantedDefinitions = Seq("Function1", "Function1RequestContextFutureRouteResult")
}

SwaggerDocServiceは、SwaggerHttpServiceを継承しSwagger Specに出力する情報を定義します。
最低限必要な定義はapiClasses、hostになります。apiClassesは、Swagger Specに掲載するAPIクラス(Swaggerアノテーションを定義したクラス)を羅列します。（apiClassesに含まないクラスはSwagger Specに出力されません。）hostはSwagger UIからAPI実行するためのエンドポイントのホスト情報として必要となります。
あとはAkkaのルーティングにSwaggerDocService(SwaggerDocService.route)を追加して終わりです。
Swagger Specの出力形式はjson形式、yaml形式の両方があります。アプリを起動し、以下のでURLにアクセスすれば出力可能です。

json形式はこちら → http://localhost:12345/api-docs/swagger.json
yaml形式はこちら → http://localhost:12345/api-docs/swagger.yaml

※ アクセスのパスの「/api-docs/」はSwaggerDocService内の定義で変更可能です。