{"id":17160526,"url":"https://github.com/mattpolzin/jsonapi-openapi","last_synced_at":"2025-04-13T14:10:35.316Z","repository":{"id":53487446,"uuid":"168446016","full_name":"mattpolzin/JSONAPI-OpenAPI","owner":"mattpolzin","description":"A library that adds support for generating OpenAPI compliant documentation from JSON API compliant models.","archived":false,"fork":false,"pushed_at":"2024-02-15T18:28:46.000Z","size":412,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T06:21:36.272Z","etag":null,"topics":["jsonapi","openapi-documentation","openapi3","swift","swift-library"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattpolzin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-31T01:58:58.000Z","updated_at":"2024-09-23T00:53:20.000Z","dependencies_parsed_at":"2023-11-06T05:22:12.363Z","dependency_job_id":"defe9f5a-cc72-4e94-80f7-f968fba50099","html_url":"https://github.com/mattpolzin/JSONAPI-OpenAPI","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI-OpenAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI-OpenAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI-OpenAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI-OpenAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattpolzin","download_url":"https://codeload.github.com/mattpolzin/JSONAPI-OpenAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724629,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jsonapi","openapi-documentation","openapi3","swift","swift-library"],"created_at":"2024-10-14T22:25:08.086Z","updated_at":"2025-04-13T14:10:35.294Z","avatar_url":"https://github.com/mattpolzin.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSONAPI+OpenAPI\n[![MIT license](http://img.shields.io/badge/license-MIT-lightgrey.svg)](http://opensource.org/licenses/MIT) [![Swift 5.9](http://img.shields.io/badge/Swift-5.9-blue.svg)](https://swift.org) [![Build Status](https://app.bitrise.io/app/2ae0b5578e1905b8/status.svg?token=T8UAUN08e1_GnYk1z3P98g\u0026branch=main)](https://app.bitrise.io/app/2ae0b5578e1905b8)\n\nSee parent project: https://github.com/mattpolzin/JSONAPI\n\nThe `JSONAPIOpenAPI` framework adds the ability to generate OpenAPI compliant JSON Schema documentation of a JSONAPI Document.\n\nThere 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.\n\nSee the Open API Spec here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md\n\n*This library has many loose ends and very little documentation. The documentation will grow as the framework becomes more complete.*\n\n## Running and Testing\nAs 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.\n\n## _Experimental_ Swift Code Generation\n\nThe 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.\n\n## _Experimental_ Graphviz (DOT) Generation\n\nThe 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.\n\n## OpenAPI JSON Schema Generation\n### Simple Example\nYou can try this out in the included Playground.\n\n```swift\nimport Foundation\nimport JSONAPI\nimport OpenAPIKit\nimport JSONAPIOpenAPI\nimport Sampleable\n\nlet encoder = JSONEncoder()\nencoder.outputFormatting = .prettyPrinted\n\n//\n// First describe the resource object\n//\nstruct WidgetDescription: JSONAPI.ResourceObjectDescription {\n    static var jsonType: String { return \"widgets\" }\n\n    struct Attributes: JSONAPI.Attributes {\n        let productName: Attribute\u003cString\u003e\n    }\n\n    struct Relationships: JSONAPI.Relationships {\n        let subcomponents: ToManyRelationship\u003cWidget, NoMetadata, NoLinks\u003e\n    }\n}\n\ntypealias Widget = JSONAPI.ResourceObject\u003cWidgetDescription, NoMetadata, NoLinks, String\u003e\n\n//\n// Then make things sampleable\n// This is needed because the only way to use reflection on\n// your attributes and relationships structs is to create\n// instances of them.\n//\nextension WidgetDescription.Attributes: Sampleable {\n    static var sample: WidgetDescription.Attributes {\n        return .init(productName: .init(value: \"Fillihizzer Nob Hub\"))\n    }\n}\n\nextension WidgetDescription.Relationships: Sampleable {\n    static var sample: WidgetDescription.Relationships {\n        return .init(subcomponents: .init(ids: [.init(rawValue: \"1\")]))\n    }\n}\n\n//\n// We can create a JSON Schema for the Widget at this point\n//\nlet widgetJSONSchema = Widget.openAPISchema(using: encoder)\n\n//\n// Describe a JSON:API response body with 1 widget and\n// any number of related widgets included.\n//\ntypealias SingleWidgetDocumentWithIncludes = Document\u003cSingleResourceBody\u003cWidget\u003e, NoMetadata, NoLinks, Include1\u003cWidget\u003e, NoAPIDescription, BasicJSONAPIError\u003cString\u003e\u003e\n\n//\n// Finally we can create a JSON Schema for the response body of a successful request\n//\nlet jsonAPIResponseSchema = SingleWidgetDocumentWithIncludes.SuccessDocument.openAPISchema(using: encoder)\n\nprint(String(data: try! encoder.encode(jsonAPIResponseSchema), encoding: .utf8)!)\n\n//\n// Or a failed request\n//\nlet jsonAPIResponseErrorSchema = SingleWidgetDocumentWithIncludes.ErrorDocument.openAPISchema(using: encoder)\n\n//\n// Or a schema describing the response as `oneOf` the success or error respones\n//\nlet jsonAPIResponseFullSchema = SingleWidgetDocumentWithIncludes.openAPISchema(using: encoder)\n```\n\nThe above code produces:\n```json\n{\n  \"type\" : \"object\",\n  \"properties\" : {\n    \"data\" : {\n      \"type\" : \"object\",\n      \"properties\" : {\n        \"relationships\" : {\n          \"type\" : \"object\",\n          \"properties\" : {\n            \"subcomponents\" : {\n              \"type\" : \"object\",\n              \"properties\" : {\n                \"data\" : {\n                  \"type\" : \"array\",\n                  \"items\" : {\n                    \"type\" : \"object\",\n                    \"properties\" : {\n                      \"type\" : {\n                        \"type\" : \"string\",\n                        \"enum\" : [\n                          \"widgets\"\n                        ]\n                      },\n                      \"id\" : {\n                        \"type\" : \"string\"\n                      }\n                    },\n                    \"required\" : [\n                      \"id\",\n                      \"type\"\n                    ]\n                  }\n                }\n              },\n              \"required\" : [\n                \"data\"\n              ]\n            }\n          },\n          \"required\" : [\n            \"subcomponents\"\n          ]\n        },\n        \"id\" : {\n          \"type\" : \"string\"\n        },\n        \"type\" : {\n          \"type\" : \"string\",\n          \"enum\" : [\n            \"widgets\"\n          ]\n        },\n        \"attributes\" : {\n          \"type\" : \"object\",\n          \"properties\" : {\n            \"productName\" : {\n              \"type\" : \"string\"\n            }\n          },\n          \"required\" : [\n            \"productName\"\n          ]\n        }\n      },\n      \"required\" : [\n        \"attributes\",\n        \"id\",\n        \"relationships\",\n        \"type\"\n      ]\n    },\n    \"included\" : {\n      \"type\" : \"array\",\n      \"items\" : {\n        \"type\" : \"object\",\n        \"properties\" : {\n          \"relationships\" : {\n            \"type\" : \"object\",\n            \"properties\" : {\n              \"subcomponents\" : {\n                \"type\" : \"object\",\n                \"properties\" : {\n                  \"data\" : {\n                    \"type\" : \"array\",\n                    \"items\" : {\n                      \"type\" : \"object\",\n                      \"properties\" : {\n                        \"type\" : {\n                          \"type\" : \"string\",\n                          \"enum\" : [\n                            \"widgets\"\n                          ]\n                        },\n                        \"id\" : {\n                          \"type\" : \"string\"\n                        }\n                      },\n                      \"required\" : [\n                        \"type\",\n                        \"id\"\n                      ]\n                    }\n                  }\n                },\n                \"required\" : [\n                  \"data\"\n                ]\n              }\n            },\n            \"required\" : [\n              \"subcomponents\"\n            ]\n          },\n          \"id\" : {\n            \"type\" : \"string\"\n          },\n          \"type\" : {\n            \"type\" : \"string\",\n            \"enum\" : [\n              \"widgets\"\n            ]\n          },\n          \"attributes\" : {\n            \"type\" : \"object\",\n            \"properties\" : {\n              \"productName\" : {\n                \"type\" : \"string\"\n              }\n            },\n            \"required\" : [\n              \"productName\"\n            ]\n          }\n        },\n        \"required\" : [\n          \"attributes\",\n          \"id\",\n          \"relationships\",\n          \"type\"\n        ]\n      },\n      \"uniqueItems\" : true\n    }\n  },\n  \"required\" : [\n    \"included\",\n    \"data\"\n  ]\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattpolzin%2Fjsonapi-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattpolzin%2Fjsonapi-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattpolzin%2Fjsonapi-openapi/lists"}