{"id":13871845,"url":"https://github.com/dankinsoid/SwiftOpenAPI","last_synced_at":"2025-07-16T01:31:56.951Z","repository":{"id":89408658,"uuid":"607038304","full_name":"dankinsoid/SwiftOpenAPI","owner":"dankinsoid","description":"Swift library which can generate output compatible with OpenAPI 3.1.0","archived":false,"fork":false,"pushed_at":"2024-09-21T10:48:00.000Z","size":349,"stargazers_count":9,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-30T17:21:11.175Z","etag":null,"topics":["openapi","swift"],"latest_commit_sha":null,"homepage":"","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/dankinsoid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":"dankinsoid","open_collective":"voidilov-daniil","ko_fi":"dankinsoid","custom":["https://paypal.me/voidilovuae"]}},"created_at":"2023-02-27T07:17:32.000Z","updated_at":"2024-09-21T10:48:04.000Z","dependencies_parsed_at":"2023-12-09T20:33:07.586Z","dependency_job_id":"67b9cebd-f2ac-4fb4-99a0-dcb60c113f15","html_url":"https://github.com/dankinsoid/SwiftOpenAPI","commit_stats":{"total_commits":40,"total_committers":1,"mean_commits":40.0,"dds":0.0,"last_synced_commit":"d293bcbbdee7609814d6b6c2c9e20a0820715167"},"previous_names":[],"tags_count":98,"template":false,"template_full_name":"dankinsoid/iOSLibraryTemplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankinsoid%2FSwiftOpenAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankinsoid%2FSwiftOpenAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankinsoid%2FSwiftOpenAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankinsoid%2FSwiftOpenAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dankinsoid","download_url":"https://codeload.github.com/dankinsoid/SwiftOpenAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226089972,"owners_count":17572112,"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":["openapi","swift"],"created_at":"2024-08-05T23:00:28.064Z","updated_at":"2025-07-16T01:31:56.928Z","avatar_url":"https://github.com/dankinsoid.png","language":"Swift","funding_links":["https://github.com/sponsors/dankinsoid","https://opencollective.com/voidilov-daniil","https://ko-fi.com/dankinsoid","https://paypal.me/voidilovuae"],"categories":["Swift"],"sub_categories":[],"readme":"# SwiftOpenAPI\n\n[![build](https://github.com/dankinsoid/SwiftOpenAPI/actions/workflows/test.yml/badge.svg)](https://github.com/dankinsoid/SwiftOpenAPI/actions/workflows/test.yml)\n[![Version](https://img.shields.io/cocoapods/v/SwiftOpenAPI.svg?style=flat)](https://cocoapods.org/pods/SwiftOpenAPI)\n[![License](https://img.shields.io/cocoapods/l/SwiftOpenAPI.svg?style=flat)](https://cocoapods.org/pods/SwiftOpenAPI)\n[![Platform](https://img.shields.io/cocoapods/p/SwiftOpenAPI.svg?style=flat)](https://cocoapods.org/pods/SwiftOpenAPI)\n\n\n## Description\nSwiftOpenAPI is a Swift library which can generate output compatible with [OpenAPI](https://swagger.io/specification/) version 3.1.0. You can describe your API using `OpenAPIObject` type.\\\nThe main accent in the library is on simplifying the syntax: the active use of literals (array, dictionary, string etc) and static methods greatly simplifies writing and reading `OpenAPI` docs in `Swift`.\n\n## Short example\n```swift\ntry OpenAPIObject(\n    openapi: \"3.0.11\",\n    info: InfoObject(\n        title: \"Example API\",\n        version: \"0.1.0\"\n    ),\n    servers: [\n        \"https://example-server.com\",\n        \"https://example-server-test.com\"\n    ],\n    paths: [\n        \"services\": .get(\n            summary: \"Get services\",\n            OperationObject(description: \"Get services\")\n        ),\n        \"login\": .post(\n            OperationObject(\n                description: \"login\",\n                requestBody: .ref(components: \\.requestBodies, \"LoginRequest\"),\n                responses: [\n                    .ok: .ref(components: \\.responses, \"LoginResponse\"),\n                    .unauthorized: .ref(components: \\.responses, \"ErrorResponse\")\n                ]\n            )\n        ),\n        \"/services/{serviceID}\": [\n            .get: OperationObject(description: \"Get service\"),\n            .delete: OperationObject(description: \"Delete service\")\n        ],\n        \"/services\": .ref(components: \\.pathItems, \"T\")\n    ],\n    components: ComponentsObject(\n        schemas: [\n            \"LoginBody\": [\n                \"username\": .string,\n                \"password\": .string\n            ],\n            \"LoginResponse\": .value(.encode(LoginResponse.example))\n        ],\n        examples: [\n            \"LoginBody\": [\n                \"username\": \"SomeUser\",\n                \"password\": \"12345678\"\n            ],\n            \"LoginResponse\": .value(\n            \tExampleObject(value: .encode(LoginResponse.example))\n            )\n        ],\n        requestBodies: [\n            \"LoginRequest\": .value(\n                RequestBodyObject(\n                    content: [\n                        .application(.json): MediaTypeObject(\n                            schema: .ref(components: \\.schemas, \"LoginBody\")\n                        )\n                    ],\n                    required: nil\n                )\n            )\n        ]\n    )\n)\n```\n## Pets store example\n[PetsSwagger.swift](Tests/SwiftOpenAPITests/Mocks/PetsSwagger.swift) demonstrates syntaxis well\n\n## Creating schemas and parameters for `Codable` types\nThere is a possibility to create `SchemeObject`, `[ParameterObject]`, `AnyValue` and `[String: HeaderObject]` instances from `Codable` types. It's possible to use `SchemeObject.decode/encode`, `[ParameterObject].decode/encode`, `[String: HeaderObject].decode/encode` and `AnyValue.encode` methods for it.\n```swift\nlet loginBodySchemeFromType: SchemeObject = try .decode(LoginBody.self)\nlet loginBodySchemeFromInstance: SchemeObject = try .encode(LoginBody.example)\nlet loginBodyExample = try ExampleObject(value: .encode(LoginBody.example))\n```\nYou can customize the encoding/decoding result by implementing `OpenAPIDescriptable` and `OpenAPIType` protocols.\n1. `OpenAPIDescriptable` protocol allows you to provide a custom description for the type and its properties. `@OpenAPIAutoDescriptable` macro implements this protocol with your comments.\n```swift\nimport SwiftOpenAPI\n\n@OpenAPIDescriptable\n/// Login request body.\nstruct LoginBody: Codable {\n    \n    /// Username string.\n    let username: String\n    /// Password string. Encoded.\n    let password: String\n}\n```\nManually:\n```swift\nstruct LoginBody: Codable, OpenAPIDescriptable {\n    \n    let username: String\n    let password: String\n    \n    static var openAPIDescription: OpenAPIDescriptionType? {\n        OpenAPIDescription\u003cCodingKeys\u003e(\"Login request body.\")\n            .add(for: .username, \"Username string.\")\n            .add(for: .password, \"Password string. Encoded.\")\n    }\n}\n```\n2. `OpenAPIType` protocol allows you to provide a custom schema for the type.\n```swift\nstruct Color: Codable, OpenAPIType {\n    \n    static var openAPISchema: SchemaObject {\n        .string(format: \"hex\", description: \"Color in hex format\")\n    }\n}\n```\n\n## Specification extensions\nWhile the OpenAPI Specification tries to accommodate most use cases, [additional data](https://swagger.io/specification/#specification-extensions) can be added to extend the specification at certain points.\\\n```swift\nvar api = OpenAPIObject(...)\napi.specificationExtensions = [\"x-some-extension\": \"some value\"]\n// or\napi.specificationExtensions = try? SpecificationExtensions(from: someEncodable)\n```\nIt was a bit tricky challenge to implement additional dynamic properties for any codable struct. The solution is to use `SpecificationExtendable` protocol in combination with `WithSpecExtensions` property wrapper.\nThere is two ways to decode/encode `SpecificationExtendable` types with additional properties:\n1. Use `SpecificationExtendable.json`, `SpecificationExtendable.Type.from(json:)` methods.\n```swift\nlet schema = try SchemaObject.from(json: jsonData)\nlet jsonData = try schema.json()\n```\n2. If you cannot use custom decoding methods, you can use `WithSpecExtensions` wrapper.\n```swift\nlet api = try WithSpecExtensions(wrappedValue: OpenAPIObject(...))\nlet jsonData = try JSONEncoder().encode(api)\n```\n\n## TODO\n- `URI` type instead of `String`\n- `refactor` method on `OpenAPIObject` (?)\n- Extend `RuntimeExpression` type\n- `DataEncodingFormat`\n\n## Installation\n\n1. [Swift Package Manager](https://github.com/apple/swift-package-manager)\n\nCreate a `Package.swift` file.\n```swift\n// swift-tools-version:5.9\nimport PackageDescription\n\nlet package = Package(\n  name: \"SomeProject\",\n  dependencies: [\n    .package(url: \"https://github.com/dankinsoid/SwiftOpenAPI.git\", from: \"2.23.0\")\n  ],\n  targets: [\n    .target(name: \"SomeProject\", dependencies: [\"SwiftOpenAPI\"])\n  ]\n)\n```\n```ruby\n$ swift build\n```\n\n## Related projects\n- [VaporToOpenAPI](https://github.com/dankinsoid/VaporToOpenAPI.git)\n\n## Author\n\ndankinsoid, voidilov@gmail.com\n\n## License\n\nSwiftOpenAPI is available under the MIT license. See the LICENSE file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdankinsoid%2FSwiftOpenAPI","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdankinsoid%2FSwiftOpenAPI","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdankinsoid%2FSwiftOpenAPI/lists"}