Swiftpack.co - mattpolzin/OpenAPIReflection as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by mattpolzin.
mattpolzin/OpenAPIReflection 1.0.1
Additional support for turning Swift Types into OpenAPISchema
⭐️ 15
🕓 3 weeks ago
.package(url: "https://github.com/mattpolzin/OpenAPIReflection.git", from: "1.0.1")

Swift 5.1+

MIT license Tests

OpenAPI support

See parent library at https://github.com/mattpolzin/OpenAPIKit


This library offers extended support for creating OpenAPI types from Swift types. Specifically, this library covers the subset of Swift types that require a JSONEncoder to either make an educated guess at the JSONSchema for the type or to turn arbitrary types into AnyCodable for use as schema examples or allowed values.


Dates will create different OpenAPI representations depending on the encoding settings of the JSONEncoder passed into the schema construction method.

// encoder1 has `.iso8601` `dateEncodingStrategy`
let schema = Date().dateOpenAPISchemaGuess(using: encoder1)
// ^ equivalent to:
let sameSchema = JSONSchema.string(
  format: .dateTime

// encoder2 has `.secondsSince1970` `dateEncodingStrategy`
let schema2 = Date().dateOpenAPISchemaGuess(using: encoder2)
// ^ equivalent to:
let sameSchema = JSONSchema.number(
  format: .double

It will even try to take a guess given a custom formatter date decoding strategy.


Swift enums produce schemas with allowed values specified as long as they conform to CaseIterable, Encodable, and AnyJSONCaseIterable (the last of which is free given the former two).

enum CodableEnum: String, CaseIterable, AnyJSONCaseIterable, Codable {
  case one
  case two

let schema = CodableEnum.caseIterableOpenAPISchemaGuess(using: JSONEncoder())
// ^ equivalent, although not equatable, to:
let sameSchema = JSONSchema.string(
  allowedValues: "one", "two"


Swift structs produce a best-guess schema as long as they conform to Sampleable and Encodable

struct Nested: Encodable, Sampleable {
  let string: String
  let array: [Int]

  // `Sampleable` just enables mirroring, although you could use it to produce
  // OpenAPI examples as well.
  static let sample: Self = .init(
    string: "",
    array: []

let schema = Nested.genericOpenAPISchemaGuess(using: JSONEncoder())
// ^ equivalent and indeed equatable to:
let sameSchema = JSONSchema.object(
  properties: [
    "string": .string,
    "array": .array(items: .integer)

Custom OpenAPI type representations

You can take the protocols offered by this library and OpenAPIKit and create arbitrarily complex OpenAPI types from your own Swift types. Right now, the only form of documentation on this subject is the fully realized example over in the JSONAPI+OpenAPI library. Just look for conformances to OpenAPISchemaType and OpenAPIEncodedSchemaType.


Stars: 15
Last commit: 3 weeks ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

Fix Optional reflection
3 weeks ago

This fixes a bug where if a type that does not define its OpenAPI schema explicitly was wrapped in an Optional and then set as a property of some type for which a genericOpenAPISchemaGuess() was requested then the generic schema guess would result in the optional being represented as an explicit "some" key in the schema instead of just making the type it wraps optional.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics