{"id":29104581,"url":"https://github.com/swiftlang/swift-server-todos-tutorial","last_synced_at":"2025-09-02T20:34:54.086Z","repository":{"id":298428519,"uuid":"995168504","full_name":"swiftlang/swift-server-todos-tutorial","owner":"swiftlang","description":"A tutorial for building a server-side TODO management application using Swift.","archived":false,"fork":false,"pushed_at":"2025-06-04T17:27:27.000Z","size":408,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-28T09:41:45.433Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.swift.org/getting-started-swift-server/tutorials/getting-started-swift-server/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swiftlang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"zenodo":null}},"created_at":"2025-06-03T04:28:51.000Z","updated_at":"2025-06-20T05:53:39.000Z","dependencies_parsed_at":"2025-06-11T04:23:47.126Z","dependency_job_id":"c49e304f-2adf-4865-8de4-8ce284f7f874","html_url":"https://github.com/swiftlang/swift-server-todos-tutorial","commit_stats":null,"previous_names":["swiftlang/swift-server-todos-tutorial"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/swiftlang/swift-server-todos-tutorial","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-server-todos-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-server-todos-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-server-todos-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-server-todos-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swiftlang","download_url":"https://codeload.github.com/swiftlang/swift-server-todos-tutorial/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-server-todos-tutorial/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262514198,"owners_count":23322698,"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":[],"created_at":"2025-06-29T00:06:12.734Z","updated_at":"2025-06-29T00:06:14.612Z","avatar_url":"https://github.com/swiftlang.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwiftServerTodos – a Swift server tutorial\n\nA tutorial for building a server-side TODO management application using Swift.\n\n## Overview\n\nSwiftServerTodos demonstrates building an HTTP service in Swift. This repository contains a tutorial and code samples for creating a backend service using Vapor, OpenAPI, and PostgreSQL.\n\n**Contents:**\n* `SwiftServerTodos.docc`: DocC tutorial with step-by-step instructions.\n* `\u003croot directory\u003e`: Starter code for tutorial exercises.\n* `Completed`: Completed implementation for reference.\n\n## Tutorial topics\n\nThe tutorial covers these Swift server development topics:\n\n* HTTP service implementation with Vapor.\n* Code generation from an OpenAPI document.\n* Database persistence using the Fluent ORM and PostgreSQL.\n* Service configuration and lifecycle management.\n\n## Requirements\n\n* [Swift 6.1 or later](http://swift.org/install)\n* Git\n* Docker Compose\n\n## Getting started\n\n### Clone the repository\n\n```bash\ngit clone https://github.com/swiftlang/swift-server-todos-tutorial\ncd SwiftServerTodos\n```\n\n### Follow the tutorial\n\nTo preview the tutorial locally:\n\n```bash\nxcrun docc preview -p 8090\n```\n\nThe tutorial is available at `http://localhost:8090/tutorials/getting-started-swift-server`.\n\n### Working with the tutorial\n\n1. Open the DocC tutorial to read concepts and implementation details.\n2. Use the root directory as the starting package for the tutorial.\n3. Reference the package in the `Completed/` directory for the final implementation.\n4. Modify `Package.swift` and files in `Sources/` as you progress through the tutorial steps.\n\n## Architecture\n\nThe application uses a three-tier architecture:\n\n* **HTTP Layer**: Vapor web framework for HTTP request handling.\n* **Business Logic**: OpenAPI-generated handlers for request processing.\n* **Data Layer**: Fluent ORM for database operations with PostgreSQL.\n\n## Dependencies\n\n### Core frameworks\n* [Vapor](https://vapor.codes) – Swift web framework.\n* [Fluent ORM](https://docs.vapor.codes/fluent/overview/) – Database ORM and migrations.\n* [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator) – Code generation from OpenAPI specs.\n\n### Additional libraries\n* [Swift Log](https://swiftpackageindex.com/apple/swift-log/documentation/logging) – Logging framework.\n* [ServiceLifecycle](https://github.com/swift-server/swift-service-lifecycle) – Service lifecycle management.\n\n## API documentation\n\nThe service implements a RESTful API for TODO management:\n\n* `GET /todos` – Retrieve all todos.\n* `POST /todos` – Create a new todo.\n* `GET /todos/{id}` – Retrieve a specific todo.\n* `PUT /todos/{id}` – Update a todo.\n* `DELETE /todos/{id}` – Delete a todo.\n\nThe complete API specification is available in [`Sources/SwiftServerTodos/openapi.yaml`](Completed/Sources/SwiftServerTodos/openapi.yaml).\n\n## Related resources\n\n### Alternative frameworks\n* [Hummingbird](https://hummingbird.codes) – Alternative Swift web framework.\n* [Swift GRPC](https://github.com/grpc/grpc-swift) – gRPC framework.\n\n### Example projects\n* [Vapor server example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-vapor-server-example)\n* [Hummingbird server example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-hummingbird-server-example)\n* [HTTP client example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-async-http-client-example)\n* [Additional examples](https://github.com/apple/swift-openapi-generator/tree/main/Examples/)\n\n## Contributing\n\n### Build tutorial\n\nVerify the tutorial builds without errors or warnings using the command:\n\n```bash\nxcrun docc convert --warnings-as-errors --analyze\n```\n\n### Preview tutorial\n\nPreview the tutorial content. Run the following command, \nthen review your updates at `http://localhost:8090/tutorials/getting-started-swift-server`:\n\n```bash\nxcrun docc preview -p 8090\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftlang%2Fswift-server-todos-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswiftlang%2Fswift-server-todos-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftlang%2Fswift-server-todos-tutorial/lists"}