从 Scala 源代码(http4s)生成 Swagger / OpenAPI 规范

9

我并不是一个swagger专家,但是所有使用swagger的系统都要求你拥有JSON或YAML格式的swagger规范,定义你的API的所有端点和其他信息。

我的问题是:是否有已知的方法可以基于实际源代码生成这些规范文件? 我之所以问这个问题,是因为当你开始添加属性或返回稍微不同的结果时,很难保持端点代码和文档同步。

所以当我有了这段代码(使用http4s和RhoService):

object HelloWorld {
  val service = new RhoService {
    GET / "hello" / 'name |>> { name: String =>
      Ok(Json.obj("message" -> Json.fromString(s"Hello, ${name}")))
    }
  }
}

希望它能以某种方式生成(例如:)
/hello/{name}:
    get:
      tags:
      - "HelloWorld"
      summary: ""
      description: ""
      operationId: "getHellobyName"
      produces:         
      - "application/json"
      parameters:
      - name: "name"
        in: "path"
        description: ""
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Hello"           
      security:
      - api_key: []
3个回答

7

免责声明:我是tapir的作者。

rho是一种可能的解决方案。另一种方法是完全将API端点的描述与业务逻辑分离。

有一个端点的描述,它是一个普通的Scala值,可以被解释为服务器(给定“业务逻辑”函数),或文档。

两个Scala库,可以提供http4s和OpenAPI解释器,它们是tapirtypeapi


有趣。我会考虑在下一个项目中使用它。 - Tom Lous

5

2
这是一个非常重要的组件,但奇怪的是没有关于它的文档。 - WeiChing 林煒清
2
Http4s/Rho的Swagger输出示例代码可以在https://github.com/http4s/rho/tree/master/examples/src/main/scala/com/http4s/rho找到。 - Big Rich

1

声明:我是endpoints4s的作者。

类似于另一个答案中提到的tapir,endpoints4s是一个库,可以为HTTP端点生成http4s服务器和OpenAPI文档。

您可以按照以下方式编写示例:

// --- This is the description of your HTTP service

import endpoints4s.algebra

case class Hello(message: String)

trait HelloWorldEndpoints
  extends algebra.Endpoints
    with algebra.JsonEntitiesFromSchemas {

  implicit val helloJsonSchema: JsonSchema[Hello] =
    field[String]("message")
     .xmap(message => Hello(message))(hello => hello.message)

  val hello: Endpoint[String, Hello] =
    endpoint(
      get(path / "hello" / segment[String]("name")),
      ok(jsonResponse[Hello])
    )

}

// --- This is an OpenApi documentation of the endpoints defined
// --- in HelloWorldEndpoints

import endpoints4s.openapi
import endpoints4s.openapi.model.{ Info, OpenApi }

object HelloWorldDocumentation
  extends HelloWorldEndpoints
    with openapi.Endpoints
    with openapi.JsonEntitiesFromSchemas {

  val api: OpenApi =
    openApi(Info(title = "Hello API", version = "1.0"))(
      hello
    )

}

// --- This is an http4s server that implements the endpoints defined
// --- in HelloWorldEndpoints

import endpoints4s.http4s
import cats.effect.IO
import org.http4s.HttpRoutes

object HelloWorld
  extends http4s.server.Endpoints[IO]
    with http4s.server.JsonEntitiesFromSchemas
    with HelloWorldEndpoints {

  val service: HttpRoutes[IO] = HttpRoutes.of(
    routesFromEndpoints(
      hello.implementedBy(name => Hello(s"Hello, ${name}"))
    )
  )

}

// --- And this is an http4s service that publishes the OpenApi documentation

object OpenApiServer
  extends http4s.server.Endpoints[IO]
    with http4s.server.JsonEntitiesFromEncodersAndDecoders {

  val openApiService: HttpRoutes[IO] = HttpRoutes.of(
    routesFromEndpoints(
      endpoint(
        get(path / "open-api.json"),
        ok(jsonResponse[OpenApi])
      ).implementedBy(_ => HelloWorldDocumentation.api)
    )
  )

}

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接