一个 Swift 包，用于编码成符合 JSON API 规范的请求和响应，以及从符合 JSON API 规范的请求和响应中解码。

请在此处查看 JSON API 规范：https://jsonapi.fullstack.org.cn/format/

⚠️以下 Google Colab 示例的代码是正确的，但 Google Colab Swift 编译器有时可能会出现错误，声称无法构建 JSONAPI 库。

• 基础示例
• 复合示例
• 元数据示例
• 自定义错误示例
• PATCH 示例
• 资源存储示例 (使用 JSONAPI-ResourceStorage)

• GET 示例
• POST 示例

当服务器负责序列化，客户端负责反序列化时，此库工作良好。查看示例。

• JSONAPI
  • 主要目标
  • 开发环境
    • 先决条件
    • Swift Package Manager
    • Xcode 项目
    • CocoaPods
    • 运行 Playground
  • 项目状态
  • 服务器 & 客户端示例
  • 用法
• JSONAPI+Testing
  • 字面量表达
  • 资源对象 check()
  • 比较
• JSONAPI-Arbitrary
• JSONAPI-OpenAPI
• JSONAPI-ResourceStorage

此框架的主要目标是

1. 允许创建易于在代码中使用的 Swift 类型，并且无需大量样板代码即可编码为符合 JSON API v1.0 规范的有效负载或从中解码。
2. 利用 Codable 避免额外的外部依赖，并免费获得与非 JSON 编码器/解码器的互操作性。
3. 不要牺牲类型安全。
4. 与平台无关，以便 Swift 代码可以编写一次并由客户端和服务器使用。
5. 提供人类可读的错误输出。解码 API 响应时抛出的错误和 JSONAPITesting 框架的 compare(to:) 函数的结果都具有易于理解的人类可读描述（只需使用 String(describing:)）。

需要注意的是，虽然目标是支持 JSON API 规范，但这个框架最终会对 API 规范没有明确规定的某些事情自然而然地具有倾向性。这些注意事项很大程度上是尝试以“Swifty”方式编写库的副作用。

如果您发现此库存在问题且尚未在 项目状态 下提及，请告诉我！ 我希望继续努力实现一个可以在任何应用程序中使用的库实现。

1. Swift 5.2+
2. Swift Package Manager，Xcode 11+ 或 Cocoapods

只需将以下内容包含在您软件包的依赖项中，并将 JSONAPI 添加到您的任何目标的依赖项中。

.package(url: "https://github.com/mattpolzin/JSONAPI.git", from: "5.1.0")

使用 Xcode 11+，您可以打开包含此存储库的文件夹。 不需要 Xcode 项目，但您可以使用 swift package generate-xcodeproj 生成一个。

要通过 Cocoapods 在您的项目中使用此框架，请将以下依赖项添加到您的 Podfile 中。

pod 'Poly', :git => 'https://github.com/mattpolzin/Poly.git'
pod 'MP-JSONAPI', :git => 'https://github.com/mattpolzin/JSONAPI.git'

此库不支持 Carthage 包管理器。 这是有意为之，以避免对 Xcode 和 Xcode 项目文件的额外依赖，因为它们的格式在整个版本中都在变化（除了为每个受支持的操作系统维护不同的共享方案的复杂性之外）。

支持和不支持 Carthage 之间的区别在于维护一个至少有一个共享构建方案的 Xcode 项目； 我鼓励那些需要 Carthage 支持的人 fork 这个存储库，并通过提交一个 Xcode 项目来为他们的 fork 添加支持（您可以按照上面的 Xcode 项目 部分中的描述生成一个）。 生成 Xcode 项目后，您需要将至少一个 scheme 标记为 共享。

要运行包含的 Playground 文件，请使用 Swift Package Manager 创建一个 Xcode 项目，然后在存储库的根目录中创建一个 Xcode Workspace，并将生成的 Xcode 项目和 playground 添加到 Workspace。

请注意，截至 Swift 4.2，Playground 对导入非系统 Framework 的支持仍然有点敏感。 有时构建、清理和构建，或者注释掉然后取消注释导入语句（尤其是在 Entities.swift Playground 源文件中），可以在我收到有关找不到JSONAPI的错误时使事情正常工作。

• 项目状态
• 服务器 & 客户端示例
• 用法文档

JSONAPI 框架与一个测试库打包在一起，以帮助您测试 JSONAPI 集成。 测试库称为 JSONAPITesting。 您可以在 JSONAPI 存储库中包含的 Playground 中看到 JSONAPITesting 的实际应用。

为 Attribute、ToOneRelationship 和 Id 提供了字面量表达能力，以便您可以轻松地将测试 ResourceObject 值写入单元测试中。

例如，您可以创建一个模拟的 Author（来自上面的示例），如下所示

let author = Author(
	id: "1234", // You can just use a String directly as an Id
	attributes: .init(name: "Janice Bluff"), // The name Attribute does not need to be initialized, you just use a String directly.
	relationships: .none,
	meta: .none,
	links: .none
)

ResourceObject 获得了一个 check() 函数，该函数可用于捕获 Swift 的类型系统未捕获的 JSONAPI 结构的问题。

要捕获格式错误的 JSONAPI.Attributes 和 JSONAPI.Relationships，只需在单元测试函数中调用 check()

func test_initAuthor() {
	let author = Author(...)
	Author.check(author)
}

您可以使用 JSONAPITesting 中包含的 compare(to:) 方法来比较 Documents、ResourceObjects、Attributes 等，并获得人类可读的输出。

func test_articleResponse() {
	let endToEndAPITestResponse: SingleArticleDocumentWithIncludes = ...

	let expectedResponse: SingleArticleDocumentWithIncludes = ...

	let comparison = endToEndAPITestResponse.compare(to: expectedResponse)

	XCTAssert(comparison.isSame, String(describing: comparison))
}

JSONAPI-Arbitrary 库为许多 JSONAPI 类型提供 SwiftCheck Arbitrary 一致性。

有关更多信息，请参阅 https://github.com/mattpolzin/JSONAPI-Arbitrary。

JSONAPI-OpenAPI 库为使用 JSONAPI 库构建的模型生成符合 OpenAPI 规范的 JSON Schema。 如果您的 Swift 代码是 API 信息的首选来源，那么这是一种记录 API 响应模式的简单方法。

JSONAPI-OpenAPI 还具有从 Open API 文档生成 JSONAPI Swift 代码的实验性支持（目前存在于 feature/gen-swift 分支上）。

有关更多信息，请参阅 https://github.com/mattpolzin/JSONAPI-OpenAPI。

JSONAPI-ResourceStorage 包有两个非常早期的模块，支持 JSONAPI.ResourceObjects 的存储和检索。 请将这些模块更多地视为您可以前进的两个方向的示例，而不是其他任何东西。

https://github.com/mattpolzin/JSONAPI-ResourceStorage