daltonclaybrook/apispec

Examples

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)
        ]
    }
}

Generating the JSON

Once you have defined your spec using the various protocols, you can generate OpenAPI JSON which can be used by various tools, such as Swagger UI. Assuming your Droplet conforms to APISpecProviding, your Routes file might include something like this:

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)
        }
    }
}

Package Metadata

Repository: daltonclaybrook/apispec

Default branch: master

README: README.md