https://github.com/electronicarts/kara
Automated generation of Finagle HTTP/JSON services and Swagger UI from Thrift service definitions.
https://github.com/electronicarts/kara
finagle sbt scala swagger-ui thrift
Last synced: 4 months ago
JSON representation
Automated generation of Finagle HTTP/JSON services and Swagger UI from Thrift service definitions.
- Host: GitHub
- URL: https://github.com/electronicarts/kara
- Owner: electronicarts
- License: other
- Created: 2020-08-20T18:31:55.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2022-03-28T12:35:18.000Z (over 3 years ago)
- Last Synced: 2025-06-06T06:07:33.998Z (4 months ago)
- Topics: finagle, sbt, scala, swagger-ui, thrift
- Language: Scala
- Homepage:
- Size: 5.03 MB
- Stars: 17
- Watchers: 5
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# kara
[](https://github.com/electronicarts/kara/actions)
[](https://codecov.io/gh/electronicarts/kara)
[](https://search.maven.org/artifact/com.ea.kara/kara)
[](https://github.com/electronicarts/kara/releases)
### Generate [Finagle](https://twitter.github.io/finagle/) HTTP/JSON services and [Swagger UI](https://swagger.io/tools/swagger-ui/) from [Thrift](https://thrift.apache.org/) service definitions.
------
## Purpose
Provide a quick and human-friendly way of discovering and trying out Thrift APIs, without having to compile Thrift clients for your services.
With **kara**, all your Thrift APIs can benefit from Swagger UI, where schema is exposed, and requests can be tried.
And since a HTTP/JSON API is exposed, you don't necessarily have to deal with the Swagger UI to interact with your Thrift services: you can use your favourite tools (e.g. `curl`, [Postman](https://www.postman.com/)) or anything that talks HTTP/JSON, really!
**NOTE**: while extremely useful during development, **kara** is not intended for production use.
## Usage
- Add **kara** as a plugin to the sbt project adding a line containing `addSbtPlugin("com.ea.kara" % "kara" % "0.2.2")` in `project/plugins.sbt`.
- In your project settings in `build.sbt`:
- configure `karaServices := Seq("fully_qualified_service_1", "fully_qualified_service_2, ...)` to indicate the Thrift services Kara should generate Finagle services and Swagger UI for. Services should be listed in `.` format.
- enable the the plugin with `.enablePlugins(Kara)` on the project that lists the Thrift sources and on which `ScroogeSBT` is enabled.
On compilation (`sbt compile`), a Finagle HTTP service named `Http` is generated, which takes as input an instance of a [Scrooge](http://twitter.github.io/scrooge/)-generated Thrift service `.MethodPerEndpoint`. All is left to do is to instantiate it in your app and bind it to a Finagle server on a port of your choice.
## Example
#### project/plugins.sbt
```scala
addSbtPlugin("com.ea.kara" % "kara" % "0.2.2")
```
#### build.sbt
```scala
// ...
lazy val thrift = project.in(file("thrift"))
.settings(
// ...
karaServices := Seq("path.to.ExampleService1", "path.to.ExampleService2")
).enablePlugins(Kara)
// ...
```
#### App.scala
```scala
import com.twitter.finagle.Http
// ...
val thriftSvc: Service1.MethodPerEndpoint = ???
val karaSvc: HttpService1 = new HttpExampleService1(thriftSvc)
Http.server.serve(":8080", karaSvc)
// ...
```
[Scripted tests](./src/sbt-test/kara/) are a great way to see **kara** in action.
## Dependency Map
| **kara** | **Swagger UI** | **Finagle / Scrooge** |
|:--------:|:--------------:|:---------------------:|
| 0.2.x | 3.38.0 | 20.10.0 |
| 0.1.0 | 3.31.1 | 20.5.0 |
## Testing
**kara** features two modes of testing:
- *Unit tests*, testing code generation logic:
- `sbt test`
- *E2E tests*, testing plugin functionality via [scripted](https://www.scala-sbt.org/1.x/docs/Testing-sbt-plugins.html) test framework:
- `sbt scripted`
## Developer
**kara** was born at [EA DICE](https://www.dice.se/).
## Contributing
Before you can contribute, EA must have a Contributor License Agreement (CLA) on file that has been signed by you. You can find the CLA [here](https://electronicarts.na1.echosign.com/public/esignWidget?wid=CBFCIBAA3AAABLblqZhByHRvZqmltGtliuExmuV-WNzlaJGPhbSRg2ufuPsM3P0QmILZjLpkGslg24-UJtek*).
## License
Modified BSD License (3-Clause BSD license). See [LICENSE](./LICENSE).