SwagGen

SwagGen 是一个库和命令行工具，用于解析和生成 OpenAPI/Swagger 3.0 规范的代码，完全用 Swift 编写。

已移除 Swagger 2 支持。对于 Swagger 2，请使用 3.0.2 版本或 swagger_2 分支

它包含一个 Swagger 库，可以在 Swift 中用于加载和解析 Swagger 规范。

SwagGen 是一个命令行工具，可以从 OpenAPI/Swagger 3.0 规范生成代码。可以编写任何语言的模板来利用此生成器。

SwagGen 包含一个捆绑的模板，用于生成客户端 Swift 库，以与 Swagger 规范交互。它包括对模型继承、共享枚举、离散和可变请求对象、内联模式、Codable 和 Equatable 模型、可配置选项、通用网络堆栈以及许多其他优点的支持。

请先确保已安装 Xcode 11+。

$ mint install yonaskolb/SwagGen

$ brew tap yonaskolb/SwagGen https://github.com/yonaskolb/SwagGen.git
$ brew install SwagGen

$ git clone https://github.com/yonaskolb/SwagGen.git
$ cd SwagGen
$ make install

$ git clone https://github.com/yonaskolb/SwagGen.git
$ cd swaggen
$ swift run

将以下内容添加到您的 Package.swift 文件的 dependencies 中

.package(url: "https://github.com/yonaskolb/SwagGen.git", from: "4.4.0"),

然后根据需要在任何地方导入

import SwagGenKit
import Swagger

使用 --help 查看用法信息

swaggen --help
Usage: swaggen <command> [options]

Commands:
  generate        Generates a template from a Swagger spec
  help            Prints this help information
  version         Prints the current version of this app

swaggen generate path_to_spec

使用 swaggen generate --help 查看生成选项列表。

• spec：这是 Swagger 规范的路径，是必需参数。它可以是文件路径或 YAML 或 JSON 文件的网址

• --language：要为其生成模板的语言。目前默认为 swift。

• --template：：这是模板配置 yaml 文件的路径。它可以是文件的直接路径，也可以是父目录的路径，默认情况下将在其中查找 /template.yml。如果未传递此参数，将使用该语言的默认模板。

• --destination：生成的文件将添加到的目录。

• --option：一个选项，将与模板配置选项合并，此参数中的选项优先，这意味着将覆盖任何同名的现有选项。可以重复此参数以传入多个选项。选项必须指定选项名称和选项值，以冒号分隔，任何空格都包含在引号中。可以通过使用点语法来设置字典中的嵌套选项。允许以下格式

  • -- option myOption:myValue
  • -- option modelSuffix: Model
  • -- option propertyNames.identifier: id
  • -- option "myOption: my value"

• --clean：控制是否以及如何清理目标目录中未生成的文件。选项包括

  • none：不删除任何文件（默认）
  • all：删除所有其他文件
  • leave.files：删除目标目录中除以 . 开头的文件和目录之外的所有文件和目录。这对于保留配置文件和目录（例如 .git）很有用，同时仍然确保从规范中删除的项目也从生成的 API 中删除。

• --verbose：显示更详细的输出

• --silent：静音所有标准输出。错误仍将显示

示例

swaggen generate http://myapi.com/spec --template Templates/Swift  --destination generated --option name:MyAPI --option "customProperty: custom value --clean leave.files"

对于 Swift 模板，一个方便的选项是 name，它可以更改生成的框架的名称，使其不再是默认的 API。这可以在模板中设置，也可以通过传入 --option name:MyCoolAPI 来设置。

所有可用选项列表

如果编写自己的 Swift 模板，则需要为生成的几种类型提供类型别名

• ID：UUID 格式。通常为 UUID 或 String
• File：file 格式。通常为 URL、Data 或具有 mimeType 和 fileName 的自定义类型
• DateTime：date-time 格式。通常为 Date
• DateDay：date 格式。通常为 Date 或自定义类型。

如果要在 Xcode 中运行时传递任何必需的参数，可以编辑 scheme 以包含启动参数。

模板由模板配置文件、一堆 Stencil 文件以及在生成过程中复制的其他文件组成

这是 YAML 或 JSON 格式的模板的配置和清单文件。它可以包含

• formatter：要使用的可选格式化程序。这会影响模板中可用的属性以及它们的格式化方式，例如 Swift
• templateFiles：模板文件列表。这些文件都可以通过 Stencil 标签修改其路径、内容和目标目录。如果路径根据列表上下文更改，则一个模板文件也可以输出到多个文件。每个文件包含
  • path：相对于模板配置的路径。扩展名通常为 .stencil 或它最终将成为的类型
  • context：规范中的可选上下文。这提供给生成的文件，否则将传递完整上下文。如果这是一个列表，则将为每个对象创建一个文件，并使用该列表中的上下文。（例如，规范 definitions 中的每个模型的文件的都获取其自己的定义上下文）。请注意，模板 options 字段中的属性可以在此处使用
  • destination：可选目标路径。这可以包含 stencil 标签，其上下文来自上面的上下文。例如，如果上下文是 definitions，则路径可以是 Models/{{ type }}.swift，文件名将是定义的类型。如果省略此项，则目标将与路径相同，相对于最终目标目录。如果它解析为空字符串，则将跳过它并且不生成。
• copiedFiles：这是一个相对路径数组，将复制到目标位置。它们可以是文件或目录。这用于不会更改其内容、文件名或路径的文件。
• options：这些是传递到每个 stencil 文件中的选项，可用于自定义模板。这些选项与 options 参数合并，其中参数选项优先。这些选项可以在模板文件路径及其内容中引用。

可以在此处找到 Swift 的示例模板

这些文件遵循 https://stencil.fuller.li 中概述的 Stencil 文件格式

格式化程序更改模板可用的信息以及信息的格式化方式。可以通过模板配置中的 formatter 属性指定它们。通常，这些将映射到特定的目标语言，但可以为不同的目的进行自定义。

SwagGen 可用于生成任何语言的代码。目前，只有 Swift 的格式化程序和模板

用法文档可以在随模板生成的 Readme 中找到。

此工具由以下项目驱动：

• JSONUtilities
• Stencil
• StencilSwiftKit
• Spectre
• PathKit
• SwiftCLI
• Yams

还要感谢 Logan Shire 及其在 Swagger Parser 上的初步工作

• swagger-codegen
• CreateAPI
• OpenAPI Generator
• swift-openapi-generator

欢迎提交 pull request 和 issue

SwagGen 在 MIT 许可证下获得许可。有关更多信息，请参阅 LICENSE。