APISpec

APISpec 使得 Swift Vapor 开发者能够使用 Swift 编写 API 文档，然后将这些文档导出为 OpenAPI 3.0 JSON 格式。

要构建一个规范 (spec)，你必须使你的类型遵循以下三个协议

APISpecProviding - 此类型代表你的规范根 (spec root)。通常，你的 Droplet 将遵循此类型。
APITagProviding - 此类型代表你的规范的各个部分，在 OpenAPI 中被称为 "标签 (Tags)"，通常由控制器 (Controllers) 组成。遵循者 (Conformers) 负责提供 APIOperations，它代表你的 API 公开的端点。如果你的控制器遵循 ResourceRepresentable，并且你的 Resource 模型遵循 APISchemaProviding，你可以从你的资源生成 APIOperations。否则，你必须手动生成 APIOperations。
APISchemaProviding - 你的 API 契约 (contract) 的主要组成部分是你的模式 (schema)。 API 请求/响应数据必须遵循可预测的模式，以便客户端/服务器通信有意义。通常，你的模型 (Models) 将遵循此类型。

例子

APISpecProviding

extension Droplet: APISpecProviding {
    public var title: String {
        return "Petworld API"
    }
    public var description: String {
        return "The is the API server for Petworld."
    }
    public var host: String {
        return "api.petworld.com"
    }
    public var schemes: APISchemes {
        return .https
    }
    public var contactEmail: String? {
        return "daltonclaybrook@gmail.com"
    }
}

APITagProviding -

extension PetController: APITagProviding {
    var name: String {
        return "pets"
    }
    var description: String {
        return "Pets have various characteristics such as `name` and `owner`."
    }
    var operations: [APIOperation] {
        // You can generate APIOperations from a Resource where Model conforms to `APISchemaProviding`
        return makeResource().makeAPIOperations(withPath: "/pets")
    }
}

APISchemaProviding

extension Pet: APISchemaProviding {
    static var schemaName: String {
        return "Pet"
    }
    static var properties: [APIProperty] {
        return [
            APIProperty(name: "name", type: .string(example: "Sparky")),
            APIProperty(name: "age", type: .number(example: 3)),
            APIProperty(name: "owner", type: .object(type: Owner.self), isRequired: false)
        ]
    }
}

生成 JSON

一旦你使用各种协议定义了你的规范，你就可以生成 OpenAPI JSON，它可以被各种工具使用，例如 Swagger UI。假设你的 Droplet 遵循 APISpecProviding，你的 Routes 文件可能包含如下内容

import APISpec

extension Droplet {
    func setupRoutes() throws {
        // ... setup other routes

        let tagProviders: [APITagProviding] = [
            petController
        ]
        
        self.get("/docs.json") { _ in
            return try self.generateAPISpecResponse(with: tagProviders)
        }
    }
}