Создать спецификацию Swagger / OpenAPI из исходного кода scala (http4s)

Так что я не эксперт по чванству, но все системы, использующие чванство, требуют, чтобы у вас была спецификация чванства в JSON или YAML, определяющая все конечные точки (и т. Д.) Вашего 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: []

person Tom Lous    schedule 21.09.2017    source источник


Ответы (2)


Отказ от ответственности: я являюсь автором тапира.

Один из возможных вариантов - rho. Другой подход - полностью отделить описание конечной точки API от бизнес-логики.

Имея описание конечной точки, которое является обычным значением Scala, ее затем можно интерпретировать либо как сервер (с учетом функции «бизнес-логики»), либо как документацию.

Две библиотеки Scala, которые могут предоставлять интерпретаторы http4s и OpenAPI: tapir и typeapi.

person adamw    schedule 26.02.2019
comment
Интересно. Я посмотрю на это в следующем проекте - person Tom Lous; 04.03.2019

Это плохо документировано, но, очевидно, http4s RhoService добавляет промежуточное ПО для генерации swagger.json на основе ваших маршрутов:

Получите его, вызвав "http://localhost:8080/swagger.json"

Источник Git: https://github.com/http4s/rho/blob/0c5aed48aeeea18b1d66d88b58cd3deea733f070/swagger/src/main/scala/org/http4sala/rho/swaggerSupplow

person Tom Lous    schedule 21.09.2017
comment
такой важный компонент, что, как ни странно, о нем нет документа. - person WeiChing 林煒清; 02.03.2018
comment
Пример кода вывода Swagger Http4s / Rho можно найти по адресу https://github.com/http4s/rho/tree/master/examples/src/main/scala/com/http4s/rho - person Big Rich; 14.03.2018