{"id":13872159,"url":"https://github.com/Apodini/ApodiniMigrator","last_synced_at":"2025-07-16T01:33:02.247Z","repository":{"id":40580806,"uuid":"362228215","full_name":"Apodini/ApodiniMigrator","owner":"Apodini","description":"Automated, machine-readable Migration Guides for Apodini Web Services.","archived":false,"fork":false,"pushed_at":"2022-10-01T01:36:23.000Z","size":1594,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2024-08-06T23:51:40.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Apodini.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/MIT.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-27T19:29:27.000Z","updated_at":"2022-02-01T09:52:50.000Z","dependencies_parsed_at":"2023-01-18T21:45:18.810Z","dependency_job_id":null,"html_url":"https://github.com/Apodini/ApodiniMigrator","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":"Apodini/Template-Repository","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apodini%2FApodiniMigrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apodini%2FApodiniMigrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apodini%2FApodiniMigrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apodini%2FApodiniMigrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Apodini","download_url":"https://codeload.github.com/Apodini/ApodiniMigrator/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226090030,"owners_count":17572114,"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":"2024-08-05T23:00:35.387Z","updated_at":"2024-11-23T19:31:38.425Z","avatar_url":"https://github.com/Apodini.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"\u003c!--\n\nThis source file is part of the Apodini open source project\n\nSPDX-FileCopyrightText: 2021 Paul Schmiedmayer and the project authors (see CONTRIBUTORS.md) \u003cpaul.schmiedmayer@tum.de\u003e\n\nSPDX-License-Identifier: MIT\n\n--\u003e\n\n# Apodini Migrator\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"200\" src=\"https://github.com/Apodini/ApodiniMigrator/blob/develop/Resources/logo.png\"\u003e\n\u003c/p\u003e\n\n[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/Apodini/ApodiniMigrator/blob/develop/LICENSES)\n[![swift-version](https://img.shields.io/badge/Swift-5.5-orange.svg)](https://github.com/apple/swift)\n[![Build](https://github.com/Apodini/ApodiniMigrator/actions/workflows/build.yml/badge.svg)](https://github.com/Apodini/ApodiniMigrator/actions/workflows/build.yml)\n[![codecov](https://codecov.io/gh/Apodini/ApodiniMigrator/branch/develop/graph/badge.svg?token=5MMKMPO5NR)](https://codecov.io/gh/Apodini/ApodiniMigrator)\n\n`ApodiniMigrator` is a Swift package that performs several automated tasks, to migrate client applications after a Web Service publishes a new version that contains breaking changes. The tasks include automated generation of an intermediary client library that contains all required components to establish a client-server communication. Furthermore, `ApodiniMigrator` is able to automatically generate a machine-readable migration guide in either `json` or `yaml` format, that describes the changes between two subsequent Web API versions, and includes auxiliary migrating actions. By means of the migration guide, `ApodiniMigrator` can automatically migrate the intermediary client library, ensuring therefore the compatibility with the new Web API version. It is part of [**Apodini**](https://github.com/Apodini/Apodini), a composable framework to build Web Services in using Swift.\n\n## Requirements\n\nThis library requires at least Swift 5.5 and macOS 12. Furthermore, it makes use of an automatically generated `Document`, that describes the interface of an Apodini Web Service. See [Documentation](https://github.com/Apodini/Apodini) in *Apodini* project, on how to integrate and configure `ApodiniMigrator` in your Web Service to generate the `Document` or a migration guide between two versions.\n\n## Installation/Setup/Integration\n\n`ApodiniMigrator` offers a Command-line interface program to execute its functionalities. After cloning the project, one can run the following commands on the root of the project to install `migrator` CLI as well as the Protocol Buffer compiler plugin.\n\n```console\n$ swift build --configuration release\n$ cp -f .build/release/migrator /usr/local/bin/migrator\n$ cp -f .build/release/protoc-gen-grpc-migrator /usr/local/bin/protoc-gen-grpc-migrator\n```\n\nTo use the gRPC Apodini Migrator you will also need to install the Protocol Buffer compiler and the respective Swift plugins.\n\n```console\n$ brew install protobuf\n$ brew install swift-protobuf grpc-swift\n```\n\n## Usage\nAfter installing `migrator` CLI, `migrator --help` command gives an overview of its functionalities:\n\n```console\n$ migrator --help\nOVERVIEW: Automatically generate migration guides and migrate client libraries.\n\nUSAGE: migrator \u003csubcommand\u003e\n\nOPTIONS:\n  -h, --help              Show help information.\n\nSUBCOMMANDS:\n  compare                 Compare API documents and automatically generate a migration guide between two versions.\n  migrate                 Migrate a client library using the base API document and a migration guide.\n  generate                Generate a client library from an API document.\n\n  See 'migrator help \u003csubcommand\u003e' for detailed help.\n```\n### Compare\n\n`compare` subcommand automatically generates a machine-readable migration guide in either `json` or `yaml` format after comparing documents of two different versions. Below its required arguments:\n\n```console\n$ migrator compare --help\nOVERVIEW: Compare API documents and automatically generate a migration guide between two versions.\n\nUSAGE: migrator compare --old-document-path \u003cold-document-path\u003e --new-document-path \u003cnew-document-path\u003e --migration-guide-path \u003cmigration-guide-path\u003e [--format \u003cformat\u003e]\n\nOPTIONS:\n  -o, --old-document-path \u003cold-document-path\u003e\n                          Path to API document of the old version, e.g. /path/to/api_v1.0.0.json \n  -n, --new-document-path \u003cnew-document-path\u003e\n                          Path to API document of the new version, e.g. /path/to/api_v1.2.0.yaml \n  -m, --migration-guide-path \u003cmigration-guide-path\u003e\n                          Path to a directory where the migration guide should be persisted, e.g. /path/to/directory \n  -f, --format \u003cformat\u003e   Output format of the migration guide, either JSON or YAML. JSON by default (default: json)\n  -h, --help              Show help information.\n```\n\n### Generate\n`generate` subcommand can automatically generate an intermediary client library in the Swift programming language for supported WebAPI types.\nThe library includes all the models and API calling methods of an API Web Service and can be added as a dependency in an existing iOS or macOS using Swift Package Manager.\n\n```console\nOVERVIEW: Generate a client library from an API document.\n\nUSAGE: migrator generate \u003csubcommand\u003e\n\nOPTIONS:\n  -h, --help              Show help information.\n\nSUBCOMMANDS:\n  rest                    Generate a REST client library from an API document.\n  grpc                    Generate a gRPC client library from an API document.\n\n  See 'migrator help generate \u003csubcommand\u003e' for detailed help.\n```\n\nSubcommand for generating a RESTful client library:\n\n```console\n$ migrator generate --help\nOVERVIEW: Generate a REST client library from an API document.\n\nUSAGE: migrator generate rest --package-name \u003cpackage-name\u003e --target-directory \u003ctarget-directory\u003e --document-path \u003cdocument-path\u003e\n\nOPTIONS:\n  -n, --package-name \u003cpackage-name\u003e\n                          Name of the package \n  -t, --target-directory \u003ctarget-directory\u003e\n                          Output path of the package (without package name) \n  -d, --document-path \u003cdocument-path\u003e\n                          Path where the base api_vX.Y.Z file is located, e.g. /path/to/api_v1.0.0.json \n  -h, --help              Show help information.\n```\n\nSubcommand for generating a gRPC client library:\n\n```console\nOVERVIEW: Generate a gRPC client library from an API document.\n\nUSAGE: migrator generate grpc --package-name \u003cpackage-name\u003e --target-directory \u003ctarget-directory\u003e --document-path \u003cdocument-path\u003e --proto-path \u003cproto-path\u003e [--protoc-gen-dump-request-path \u003cprotoc-gen-dump-request-path\u003e] [--protoc-grpc-plugin-path \u003cprotoc-grpc-plugin-path\u003e]\n\nOPTIONS:\n  -n, --package-name \u003cpackage-name\u003e\n                          Name of the package \n  -t, --target-directory \u003ctarget-directory\u003e\n                          Output path of the package (without package name) \n  -d, --document-path \u003cdocument-path\u003e\n                          Path where the base api_vX.Y.Z file is located, e.g. /path/to/api_v1.0.0.json \n  -p, --proto-path \u003cproto-path\u003e\n                          Path where the grpc proto file is located, e.g. /path/to/MyWebService.proto \n  --protoc-gen-dump-request-path \u003cprotoc-gen-dump-request-path\u003e\n                          Specify the path to which you want to dump the protoc plugin request binary. For Debugging purposes! \n  --protoc-grpc-plugin-path \u003cprotoc-grpc-plugin-path\u003e\n                          Manually specify the path to the `protoc-gen-grpc-migrator` protoco plugin. \n  -h, --help              Show help information.\n```\n\n### Migrate\n\n`migrate` subcommand performs the automated migration of the intermediary client library generated in the previous step.\nIt makes use of the machine-readable migration guide and the `Document` that initially generated the library:\n\n```console\nOVERVIEW: Migrate a client library using the base API document and a migration guide.\n\nUSAGE: migrator migrate \u003csubcommand\u003e\n\nOPTIONS:\n  -h, --help              Show help information.\n\nSUBCOMMANDS:\n  rest                    Migrate a gRPC client library from an API document and a migration guide.\n  grpc                    Migrate a gRPC client library from proto files, an API document and a migration guide.\n\n  See 'migrator help migrate \u003csubcommand\u003e' for detailed help.\n```\n\nSubcommand for migrating a RESTful client library:\n\n```console\n$ migrator migrate --help\nOVERVIEW: Migrate a gRPC client library from an API document and a migration guide.\n\nUSAGE: migrator migrate rest --package-name \u003cpackage-name\u003e --target-directory \u003ctarget-directory\u003e --document-path \u003cdocument-path\u003e --migration-guide-path \u003cmigration-guide-path\u003e\n\nOPTIONS:\n  -n, --package-name \u003cpackage-name\u003e\n                          Name of the package \n  -t, --target-directory \u003ctarget-directory\u003e\n                          Output path of the package (without package name) \n  -d, --document-path \u003cdocument-path\u003e\n                          Path where the base api_vX.Y.Z file is located, e.g. /path/to/api_v1.0.0.json \n  -m, --migration-guide-path \u003cmigration-guide-path\u003e\n                          Path where the migration guide is located, e.g. /path/to/migration_guide.json \n  -h, --help              Show help information.\n```\n\nSubcommand for generating a gRPC client library:\n\n```console\nOVERVIEW: Migrate a gRPC client library from proto files, an API document and a migration guide.\n\nUSAGE: migrator migrate grpc --package-name \u003cpackage-name\u003e --target-directory \u003ctarget-directory\u003e --document-path \u003cdocument-path\u003e --migration-guide-path \u003cmigration-guide-path\u003e --proto-path \u003cproto-path\u003e [--protoc-gen-dump-request-path \u003cprotoc-gen-dump-request-path\u003e] [--protoc-grpc-plugin-path \u003cprotoc-grpc-plugin-path\u003e]\n\nOPTIONS:\n  -n, --package-name \u003cpackage-name\u003e\n                          Name of the package \n  -t, --target-directory \u003ctarget-directory\u003e\n                          Output path of the package (without package name) \n  -d, --document-path \u003cdocument-path\u003e\n                          Path where the base api_vX.Y.Z file is located, e.g. /path/to/api_v1.0.0.json \n  -m, --migration-guide-path \u003cmigration-guide-path\u003e\n                          Path where the migration guide is located, e.g. /path/to/migration_guide.json \n  -p, --proto-path \u003cproto-path\u003e\n                          Path where the grpc proto file is located, e.g. /path/to/MyWebService.proto \n  --protoc-gen-dump-request-path \u003cprotoc-gen-dump-request-path\u003e\n                          Specify the path to which you want to dump the protoc plugin request binary. For Debugging purposes! \n  --protoc-grpc-plugin-path \u003cprotoc-grpc-plugin-path\u003e\n                          Manually specify the path to the `protoc-gen-grpc-migrator` protoco plugin. \n  -h, --help              Show help information.\n```\n\n## ApodiniMigratorExample\n\n[ApodiniMigratorExample](https://github.com/Apodini/ApodiniMigratorExample) includes two different versions of an Apodini Web Service using `ApodiniMigrator` configuration. The corresponding documents of those versions can be found in the [ExampleDocuments](https://github.com/Apodini/ApodiniMigrator/tree/develop/Resources/ExampleDocuments) of this repository. In order to test out the functionalities of `migrator` CLI, a preconfigured Ruby script in the root of this repository can be used (see [migrator](https://github.com/Apodini/ApodiniMigrator/blob/develop/migrator))\n\nIn order to generate the intermediary client library for the initial version run the script with `generate` argument:\n\n```console\n$ ./migrator generate\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Starting generation of package QONECTIQ\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Starting library generation at: ~\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Creating directory Sources at: ~/QONECTIQ\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Creating directory QONECTIQ at: ~/QONECTIQ/Sources\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Creating directory Endpoints at: ~/QONECTIQ/Sources/QONECTIQ\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Handling library composite EndpointsMigrator at: ~/QONECTIQ/Sources/QONECTIQ/Endpoints\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Rendering file Event+Endpoint.swift at: ~/QONECTIQ/Sources/QONECTIQ/Endpoints\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Rendering file HomeFeed+Endpoint.swift at: ~/QONECTIQ/Sources/QONECTIQ/Endpoints\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : ...\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Package QONECTIQ was generated successfully. You can open the package via QONECTIQ/Package.swift\n\n```\nEach endpoint of the library can be accessed via the caseless enumeration `API` as follows:\n\n```swift\nAPI.getEventWithID(id: UUID())\n    .sink { completion in\n        if case let .failure(error) = completion {\n            print(\"Failed to get the event with error: \\(error)\")\n        }\n    } receiveValue: { event in\n        print(\"Received event \\(event.title)\")\n    }\n```\n\nMigration guide can be generated via:\n\n```console\n$ ./migrator compare\ninfo org.apodini.migrator : Starting generation of the migration guide...\ninfo org.apodini.migrator : Migration guide was generated successfully at /path/to/ApodiniMigrator/Resources/ExampleDocuments/migration_guide.json.\n```\n\nOnce the migration guide has been generated, use `migrate` argument to migrate the initial library:\n\n```console\n$ ./migrator migrate\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Starting migration of package QONECTIQ\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Starting library generation at: ~\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Creating directory Sources at: ~/QONECTIQ\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Creating directory QONECTIQ at: ~/QONECTIQ/Sources\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Creating directory Endpoints at: ~/QONECTIQ/Sources/QONECTIQ\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Handling library composite EndpointsMigrator at: ~/QONECTIQ/Sources/QONECTIQ/Endpoints\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Rendering file Event+Endpoint.swift at: ~/QONECTIQ/Sources/QONECTIQ/Endpoints\n2022-02-09T00:24:50+0100 info org.apodini.migrator.rest : Rendering file HomeFeed+Endpoint.swift at: ~/QONECTIQ/Sources/QONECTIQ/Endpoints\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : ...\n2022-02-08T23:08:31+0100 info org.apodini.migrator.rest : Package QONECTIQ was migrated successfully. You can open the package via QONECTIQ/Package.swift\n```\n\n## Contributing\nContributions to the projects are welcome. Please make sure to read the [contribution guidelines](https://github.com/Apodini/.github/blob/release/CONTRIBUTING.md) first.\n\n## License\nThis project is licensed under the MIT License. See [License](https://github.com/Apodini/ApodiniMigrator/blob/develop/LICENSES) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FApodini%2FApodiniMigrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FApodini%2FApodiniMigrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FApodini%2FApodiniMigrator/lists"}