7

所以我不是 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: []
4

3 回答 3

4

它没有很好地记录，但显然 http4s'RhoService添加了中间件以swagger.json根据您的路由生成：

通过调用' http://localhost:8080/swagger.json '来获取它

Git源码：https ://github.com/http4s/rho/blob/0c5aed48aeeea18b1d66d88b58cd3deea733f070/swagger/src/main/scala/org/http4s/rho/swagger/SwaggerSupport.scala#L30

于 2017-09-21T12:39:43.033 回答
4

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

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

拥有一个端点的描述，它是一个常规的 Scala 值，它可以被解释为一个服务器（给定“业务逻辑”功能）或文档。

可以提供 http4s 和 OpenAPI 解释器的两个 Scala 库是tapir和typeapi。

于 2019-02-26T10:11:15.850 回答
0

免责声明：我是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)
    )
  )

}
于 2022-01-07T11:27:51.003 回答