https://github.com/mattpolzin/OpenAPIReflection

Additional support for turning Swift Types into OpenAPISchema
https://github.com/mattpolzin/OpenAPIReflection

Last synced: 3 months ago
JSON representation

Additional support for turning Swift Types into OpenAPISchema

• Host: GitHub
• URL: https://github.com/mattpolzin/OpenAPIReflection
• Owner: mattpolzin
• License: mit
• Created: 2020-03-05T07:39:22.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2023-11-06T02:40:21.000Z (about 1 year ago)
• Last Synced: 2024-08-07T06:44:19.338Z (3 months ago)
• Language: Swift
• Size: 62.5 KB
• Stars: 18
• Watchers: 3
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
[![Swift 5.8+](http://img.shields.io/badge/Swift-5.8+-blue.svg)](https://swift.org)

[![MIT license](http://img.shields.io/badge/license-MIT-lightgrey.svg)](http://opensource.org/licenses/MIT) ![Tests](https://github.com/mattpolzin/OpenAPIReflection/workflows/Tests/badge.svg)

# OpenAPI support

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

To generate OpenAPI 3.1.x types, use the `OpenAPIReflection` module. To generate OpenAPI 3.0.x types, use the `OpenAPIReflection30` module.

# OpenAPIReflection

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

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

```swift

// 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.

## Enums

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

```swift

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"

)

```

## Structs

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

```swift

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](https://github.com/mattpolzin/JSONAPI-OpenAPI) library. Just look for conformances to `OpenAPISchemaType` and `OpenAPIEncodedSchemaType`.