diff --git a/.github/workflows/contributor-license-agreement.yml b/.github/workflows/contributor-license-agreement.yml index 561f47e..c53bb6f 100644 --- a/.github/workflows/contributor-license-agreement.yml +++ b/.github/workflows/contributor-license-agreement.yml @@ -14,6 +14,7 @@ permissions: jobs: claAssistant: + if: false # disabled until a CLA exists runs-on: ubuntu-latest steps: - name: "CLA Assistant" diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index a68bc24..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,29 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - - - -## [Unreleased] - yyyy-mm-dd - - -### Added -- [TICKET-n](http://tickets.diconium.com/browse/TICKET-n) - MINOR tickets or PATCH tickets - -### Changed - - [TICKET-n](http://tickets.diconium.com/browse/TICKET-n) - CHANGES - -### Fixed -- [TICKET-n](http://tickets.diconium.com/browse/TICKET-n) - FIXES -## [0.0.9] - 2024-05-07 - -### Added -- readme, templates and documentation - -### Changed -- (none) - -### Fixed -- (none) \ No newline at end of file diff --git a/CLA.md b/CLA.md deleted file mode 100644 index 0601a09..0000000 --- a/CLA.md +++ /dev/null @@ -1 +0,0 @@ -tbd diff --git a/CODING_GUIDELINES.md b/CODING_GUIDELINES.md index 9647873..8819d16 100644 --- a/CODING_GUIDELINES.md +++ b/CODING_GUIDELINES.md @@ -1,22 +1,6 @@ # Coding Guidelines -- You can validate that your code complies with these guidelines by running `stuff/php-format.py validate` -- Tabs, no spaces -- End of line should should be Unix style (`\n`), not Windows style (`\r\n`) -- Opening brackets goes in the same line as the last statement -``` - if (condition) { - stuff; - } -``` -- A space between keywords and parenthesis for: `if`, `else`, `while`, `switch`, `catch`, `function` -- Function calls have no space before the parentheses -- No spaces are left inside the parentheses -- A space after each comma, but without space before -- All binary operators must have one space before and one after -- There should not be more than one contiguous blank line -- There should be no empty comments -- You should not use block comments `/ * ... * /`, only line `// ...` -- Changes in functionality must be accompanied by their respective new / modified tests -- Exceptions must be used to report erroneous states. The use of functions that return true / false is allowed when they are expected values -- Use [RAII] (http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) when appropriate, mainly in the administration of resources (files, etc ...) +- A CI action validate the code using KtLint +- On local development you can check using `./gradlew ktlintCheck` +- On local development you can reformat using `./gradlew ktlintFormat` +- Further rules can be found in `.editorconfig` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96fd05e..c269253 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,36 +2,12 @@ - Contributing to KEBAB-KRAFTER is fairly easy. This document shows you how to get started. -## General -- The [documentation guide](https://docs) is the ideal beginner to explore the project and to get started. - ## Submitting changes -- Fork this repo - - -- Check out a new branch base and name it to what you intend to do: - - Example: - ```` - $ git checkout -b BRANCH_NAME - ```` - If you get an error, you may need to fetch fooBar first by using - ```` - $ git remote update && git fetch - ```` - - Use one branch per fix / feature -- Commit your changes - - Please provide a git message that explains what you've done - - Please make sure your commits follow the [conventions](https://github.com/diconium/mcc-network-generator/CONTRIBUTING.md#commit-messages) - - Commit to the forked repository - - Example: - ```` - $ git commit -am 'Add some fooBar' - ```` -- Push to the branch - - Example: - ```` - $ git push origin BRANCH_NAME - ```` -- Make a pull request - - Make sure you send the PR to the fooBar branch - +- Fork this repo https://github.com/diconium/kebab-krafter +- Check out a new branch from your fork and give it a meaningful name: +- Use one branch per fix / feature +- Commit your changes to the forked repository. Please provide a meaningful commit message +- Push your branch to your fork +- Open a pull request +- If you want to contribute, but unsure if the idea of new feature or fix is the righ direction, feel free to open an issue https://github.com/diconium/kebab-krafter/issues so we can have a chat about it. diff --git a/LICENSE_GUIDELINES.md b/LICENSE_GUIDELINES.md deleted file mode 100644 index fd9e641..0000000 --- a/LICENSE_GUIDELINES.md +++ /dev/null @@ -1 +0,0 @@ -tbd \ No newline at end of file diff --git a/README.md b/README.md index e26e6bd..70caa9e 100644 --- a/README.md +++ b/README.md @@ -16,49 +16,6 @@ Available for:
- Swift client (hopefully)

-[//]: # (Alternative logos) -[//]: # (

) - -[//]: # ( ) - -[//]: # ( Project logo) - -[//]: # (

) -[//]: # (

) - -[//]: # ( ) - -[//]: # ( Project logo) - -[//]: # (

) - -[//]: # () -[//]: # (

) - -[//]: # ( ) - -[//]: # ( Project logo) - -[//]: # (

) - -[//]: # () -[//]: # (

) - -[//]: # ( ) - -[//]: # ( Project logo) - -[//]: # (

) - -[//]: # () -[//]: # (

) - -[//]: # ( ) - -[//]: # ( Project logo) - -[//]: # (

) - --- ## 📝 Table of Contents @@ -72,16 +29,16 @@ Available for: - [Authors](#authors) - [Acknowledgments](#acknowledgement) -## 🧐 About +## About -A gradle plugin to auto-generate network interfaces from a set of swagger API documentation. +Kebab-Krafter is a gradle plugin to auto-generate network interfaces from a set of swagger API documentation. -## 🏁 Getting Started +## Getting Started To start using the plugin just add to your `build.gradle.kts` file: ```kotlin -id("com.diconium.mobile.tools.kebab-krafter") version "version" +id("com.diconium.mobile.tools.kebab-krafter") version "latest_version" ``` ### Generate Ktor Server @@ -107,67 +64,64 @@ ktorServer { } ``` -From the example above the a `InstallRoutes.kt` is generated in the `root.package.name.for.the.generated.code` with an extension function for Ktor `fun Route.installGeneratedRoutes(locator: ServiceLocator)` - -It also generates all the necessary `data class` models and controller `interfaces` that satisfy the API in a nicely unit testable way. - -The `contextSpec` is a joker card to extract any metadata needed from the `Ktor.ApplicationCall` before passing to the controller. In the sample app you can see it extracting the `accept-language` header into `Locale` object. Making the context an interface is advisable, so that it's trivial to unit test the controller by creating a `FakeContext()` +and with that you can execute `./gradlew generateKtorServer` to auto-genearted a `Route.installGeneratedRoutes`, all the `data classes` using `kotlinx-serialization` and the interfaces for each endpoint in the following format: -The `ServiceLocator` is a very simple `get` interface that can be adapted to any dependency injection you want to use. For example using Koin it would be something like: - -```kotlin -class KoinServiceLocator(private val koin: Koin) : ServiceLocator { - override fun getService(type: KClass): T = koin.get(type) +```Kotlin +public interface GetPathName { + public fun CallScope.execute(pathParameters, queryParameters, body) : ResponseBody } ``` -### Implement the Server +From that you just have to implement the interfaces! -With that generated code in place, all you gotta do is implement the interfaces and install the routes on the Ktor instance. +#### The contextSpec -Check the `sample/` app with the "Pet Store" for a full example. +The `contextSpec` is a "joker-card" to extract any metadata needed from the `Ktor.ApplicationCall` before passing to the controller. In the sample app you can see it extracting the `accept-language` header into a `Locale` object. -## 🔧 Running the tests +In the snippet above the context was named `CallScope` in the package `com.myserver.api`, a simple example for it would be: -Explain how to run the automated tests for this system. +```Kotlin +interface CallScope { + val locale: Locale // define meta-data your controller needs from the request -### Break down into end to end tests + companion object { -Explain what these tests test and why - -``` -Give an example + // define a factory function to create the object + fun from(call: ApplicationCall): CallScope = CallScopeImpl(call) + } +} ``` -### And coding style tests +Making this context an interface is advisable, so that it's trivial to unit test the controller by creating a `FakeContext()` -Explain what these tests test and why - -``` -Give an example +```Kotlin +// implement the real object separetely, to make it trivial to implement unit tests. +private class CallScopeImpl(private val call: ApplicationCall) : CallScope { + override val locale: Locale by lazy { + call.request.acceptLanguage().toLocale() + } +} ``` -## 🎈 Usage +#### The ServiceLocator -Add notes about how to use the system. +The generated `installGeneratedRoutes` receives a object of type `ServiceLocator` located in the same package of the `installGeneratedRoutes`. -## Documentation +The `ServiceLocator` is a very simple `get` interface that can be adapted to any dependency injection you want to use. For example using Koin it would be something like: -Please see [documentation guide](https://docs) +```kotlin +class KoinServiceLocator(private val koin: Koin) : ServiceLocator { + override fun getService(type: KClass): T = koin.get(type) +} +``` -## 🚀 Deployment +### Further Examples -Add additional notes about how to deploy this on a live system. +Check the `sample/` app with the "Pet Store" for a full example. -## ✍️ Authors +## Authors - [@rvp-diconium](https://github.com/rvp-diconium) See also the list of [contributors](https://github.com/diconium/mcc-network-generator/contributors) who participated in this project. - -## 🎉 Acknowledgements - -- Hat tip to anyone whose code was used -- Inspiration -- References diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index fd9e641..0000000 --- a/SECURITY.md +++ /dev/null @@ -1 +0,0 @@ -tbd \ No newline at end of file diff --git a/sample/build.gradle.kts b/sample/build.gradle.kts index 2d7f9b0..8438436 100644 --- a/sample/build.gradle.kts +++ b/sample/build.gradle.kts @@ -4,6 +4,7 @@ import com.diconium.mobile.tools.kebabkrafter.generator.KtorMapper import com.diconium.mobile.tools.kebabkrafter.generator.KtorTransformer import com.diconium.mobile.tools.kebabkrafter.models.BaseSpecModel import com.diconium.mobile.tools.kebabkrafter.models.Endpoint +import org.jetbrains.kotlin.gradle.dsl.JvmTarget private val ktorVersion: String = "2.3.12" private val kotlinVersion: String = "1.9.24" @@ -51,7 +52,11 @@ tasks.test { } kotlin { - jvmToolchain(17) + jvmToolchain(21) + compilerOptions { + jvmTarget.set(JvmTarget.JVM_21) + optIn.add("com.diconium.mobile.tools.kebabkrafter.KebabKrafterUnstableApi") + } } ktlint {