Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mattpolzin/jsonapi-openapi
A library that adds support for generating OpenAPI compliant documentation from JSON API compliant models.
https://github.com/mattpolzin/jsonapi-openapi
jsonapi openapi-documentation openapi3 swift swift-library
Last synced: 3 months ago
JSON representation
A library that adds support for generating OpenAPI compliant documentation from JSON API compliant models.
- Host: GitHub
- URL: https://github.com/mattpolzin/jsonapi-openapi
- Owner: mattpolzin
- License: mit
- Created: 2019-01-31T01:58:58.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2024-02-15T18:28:46.000Z (11 months ago)
- Last Synced: 2024-02-15T19:36:41.110Z (11 months ago)
- Topics: jsonapi, openapi-documentation, openapi3, swift, swift-library
- Language: Swift
- Size: 402 KB
- Stars: 9
- Watchers: 3
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# JSONAPI+OpenAPI
[](http://opensource.org/licenses/MIT) [](https://swift.org) [](https://app.bitrise.io/app/2ae0b5578e1905b8)
See parent project: https://github.com/mattpolzin/JSONAPI
The `JSONAPIOpenAPI` framework adds the ability to generate OpenAPI compliant JSON Schema documentation of a JSONAPI Document.
There is experimental support for generating `JSONAPI` Swift code from OpenAPI documentation in the JSONAPISwiftGen module. There is no formal documentation for this functionality, but it is an area of interest of mine. Reach out to me directly if you would like to know more.
See the Open API Spec here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
*This library has many loose ends and very little documentation. The documentation will grow as the framework becomes more complete.*
## Running and Testing
As of this writing, you need to run `swift package generate-xcodeproj` and then open that project in Xcode. Using Xcode's built-in Swift Package Manager support is currently broken for libraries like swift-syntax that require dynamic libraries from the Swift toolchain. `swift build`, `swift test`, etc. from the command line will work fine, though.
## _Experimental_ Swift Code Generation
The JSONAPISwiftGen module has experimental support for generating Swift code for `JSONAPI` models. You can dig into the source code or reach out to me for more information. This module is used by the API Test server project at [mattpolzin/jsonapi-openapi-test-server](https://github.com/mattpolzin/jsonapi-openapi-test-server) to generate models and tests.
## _Experimental_ Graphviz (DOT) Generation
The JSONAPIVizGen module has experimental support for generating Graphviz DOT files that graph out the models and relationships represented by the JSON:API/OpenAPI input. You can dig into the source code or reach out to me for more information.
## OpenAPI JSON Schema Generation
### Simple Example
You can try this out in the included Playground.
```swift
import Foundation
import JSONAPI
import OpenAPIKit
import JSONAPIOpenAPI
import Sampleable
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
//
// First describe the resource object
//
struct WidgetDescription: JSONAPI.ResourceObjectDescription {
static var jsonType: String { return "widgets" }
struct Attributes: JSONAPI.Attributes {
let productName: Attribute
}
struct Relationships: JSONAPI.Relationships {
let subcomponents: ToManyRelationship
}
}
typealias Widget = JSONAPI.ResourceObject
//
// Then make things sampleable
// This is needed because the only way to use reflection on
// your attributes and relationships structs is to create
// instances of them.
//
extension WidgetDescription.Attributes: Sampleable {
static var sample: WidgetDescription.Attributes {
return .init(productName: .init(value: "Fillihizzer Nob Hub"))
}
}
extension WidgetDescription.Relationships: Sampleable {
static var sample: WidgetDescription.Relationships {
return .init(subcomponents: .init(ids: [.init(rawValue: "1")]))
}
}
//
// We can create a JSON Schema for the Widget at this point
//
let widgetJSONSchema = Widget.openAPISchema(using: encoder)
//
// Describe a JSON:API response body with 1 widget and
// any number of related widgets included.
//
typealias SingleWidgetDocumentWithIncludes = Document, NoMetadata, NoLinks, Include1, NoAPIDescription, BasicJSONAPIError>
//
// Finally we can create a JSON Schema for the response body of a successful request
//
let jsonAPIResponseSchema = SingleWidgetDocumentWithIncludes.SuccessDocument.openAPISchema(using: encoder)
print(String(data: try! encoder.encode(jsonAPIResponseSchema), encoding: .utf8)!)
//
// Or a failed request
//
let jsonAPIResponseErrorSchema = SingleWidgetDocumentWithIncludes.ErrorDocument.openAPISchema(using: encoder)
//
// Or a schema describing the response as `oneOf` the success or error respones
//
let jsonAPIResponseFullSchema = SingleWidgetDocumentWithIncludes.openAPISchema(using: encoder)
```
The above code produces:
```json
{
"type" : "object",
"properties" : {
"data" : {
"type" : "object",
"properties" : {
"relationships" : {
"type" : "object",
"properties" : {
"subcomponents" : {
"type" : "object",
"properties" : {
"data" : {
"type" : "array",
"items" : {
"type" : "object",
"properties" : {
"type" : {
"type" : "string",
"enum" : [
"widgets"
]
},
"id" : {
"type" : "string"
}
},
"required" : [
"id",
"type"
]
}
}
},
"required" : [
"data"
]
}
},
"required" : [
"subcomponents"
]
},
"id" : {
"type" : "string"
},
"type" : {
"type" : "string",
"enum" : [
"widgets"
]
},
"attributes" : {
"type" : "object",
"properties" : {
"productName" : {
"type" : "string"
}
},
"required" : [
"productName"
]
}
},
"required" : [
"attributes",
"id",
"relationships",
"type"
]
},
"included" : {
"type" : "array",
"items" : {
"type" : "object",
"properties" : {
"relationships" : {
"type" : "object",
"properties" : {
"subcomponents" : {
"type" : "object",
"properties" : {
"data" : {
"type" : "array",
"items" : {
"type" : "object",
"properties" : {
"type" : {
"type" : "string",
"enum" : [
"widgets"
]
},
"id" : {
"type" : "string"
}
},
"required" : [
"type",
"id"
]
}
}
},
"required" : [
"data"
]
}
},
"required" : [
"subcomponents"
]
},
"id" : {
"type" : "string"
},
"type" : {
"type" : "string",
"enum" : [
"widgets"
]
},
"attributes" : {
"type" : "object",
"properties" : {
"productName" : {
"type" : "string"
}
},
"required" : [
"productName"
]
}
},
"required" : [
"attributes",
"id",
"relationships",
"type"
]
},
"uniqueItems" : true
}
},
"required" : [
"included",
"data"
]
}
```