Skip to content

Commit 76a088d

Browse files
ulrikandersenulrikandersen
authored
Interactive Playground (#348)
* Initial version of playground * Remove redundant code * Define default option on enum * Refactor * Make SEALED_INTERFACES_FOR_ONE_OF default in playground * Configure task dependencies * Deploy to fabrikt.fly.dev * Mention playground in README * Try online * Reduce intro and add try online to it * Adds workflow for deploying to Fly.io * Centralise settings parsing and enable deeplinking * Make playground tests depend on shadowJar * Only set genTypes default if query params is empty * Display version info in right most panel * Manually configure shadowJar name * Add original motivation section * Display wait cursor while generating * Fix css syntax error * Update README.md
1 parent b0e0cdd commit 76a088d

26 files changed

+1029
-13
lines changed

‎.github/workflows/deploy-playground-prod.yml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
##
2+
## Worklow for deploying the playground application to Fly.io
3+
##
4+
name: Deploy Playground (Production)
5+
on:
6+
push:
7+
branches:
8+
- master
9+
workflow_dispatch: {}
10+
11+
jobs:
12+
deploy:
13+
name: Deploy to Fly.io
14+
runs-on: ubuntu-latest
15+
concurrency: deploy-group # ensure only one action runs at a time
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: superfly/flyctl-actions/setup-flyctl@master
19+
- name: Build jar
20+
run: ./gradlew :playground:shadowJar
21+
- name: Deploy
22+
run: cd playground && flyctl deploy --remote-only
23+
env:
24+
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

‎README.md

+17-8
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# Fabrikt `/ˈfa-brikt/` - Kotlin code from OpenAPI 3
22

3-
---
4-
53
* [Introduction](#introduction)
64
* [Features](#features)
75
* [Examples](#examples)
@@ -12,12 +10,11 @@
1210
* [Maven](#maven)
1311
* [Getting the Most from Fabrikt](#getting-the-most-from-fabrikt)
1412
* [Configuration Options](#configuration-options)
13+
* [Original Motivation](#original-motivation)
1514
* [Building Locally](#building-locally)
1615
* [Publishing](#publishing)
1716
* [Specific Features](#specific-features)
1817

19-
---
20-
2118
## Introduction
2219

2320
This library was built to take advantage of the complex modeling features available in OpenAPI 3. It generates Kotlin data classes with advanced support for features such as:
@@ -33,13 +30,15 @@ This library was built to take advantage of the complex modeling features availa
3330

3431
as well as HTTP clients and controllers for a number of popular frameworks (see [Features](#features)).
3532

36-
More than just bootstrapping, this library can be permanently integrated into a gradle or maven build and will ensure contract and code always match, even as APIs evolve in complexity.
33+
More than just bootstrapping, this library can be permanently integrated into your build tool and will ensure contract and code always match, even as APIs evolve in complexity.
34+
35+
### Try Fabrikt Online
3736

38-
The team that built this tool initially contributed to the Kotlin code generation ability in [OpenApiTools](https://github.com/OpenAPITools/openapi-generator), but reached the limits of what could be achieved with template-based generation. This library leverages the rich OpenAPI 3 model provided by [KaiZen-OpenApi-Parser](https://github.com/RepreZen/KaiZen-OpenApi-Parser) and uses [Kotlin Poet](https://square.github.io/kotlinpoet/) to programmatically construct Kotlin classes for maximum flexibility.
37+
Try Fabrikt with your own API spec and see how it can help you generate code for your API clients and servers.
3938

40-
It was built at [Zalando Tech](https://opensource.zalando.com/) and is battle-tested in production there. It is particularly well-suited to API's built according to Zalando's [REST API guidelines](https://opensource.zalando.com/restful-api-guidelines/).
39+
[Fabrikt Playground](https://fabrikt.fly.dev)
4140

42-
The library is [available on Maven Central](https://search.maven.org/artifact/com.cjbooms/fabrikt) at the following coordinates:
41+
### Coordinates
4342

4443
```xml
4544
<dependency>
@@ -245,6 +244,16 @@ This section documents the available CLI parameters for controlling what gets ge
245244
| | `JAKARTA_VALIDATION` - Use `jakarta.validation` annotations in generated model classes |
246245
| | `NO_VALIDATION` - Use no validation annotations in generated model classes |
247246

247+
## Original Motivation
248+
249+
The team that built the first version of this tool initially contributed to the Kotlin code generation ability in
250+
[OpenApiTools](https://github.com/OpenAPITools/openapi-generator), but reached the limits of what could be achieved with
251+
template-based generation. This library leverages the rich OpenAPI 3 model provided by
252+
[KaiZen-OpenApi-Parser](https://github.com/RepreZen/KaiZen-OpenApi-Parser) and uses [Kotlin Poet](https://square.github.io/kotlinpoet/) to
253+
programmatically construct Kotlin classes for maximum flexibility.
254+
255+
This project was started by engineers from [Zalando Tech](https://opensource.zalando.com/) and is battle-tested heavily in production there.
256+
248257
## Building Locally
249258

250259
Fabrikt is built with Gradle and requires an initialised git repository. The easiest way to build it is to clone the repo locally before executing the build command:

‎playground/Dockerfile

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
FROM openjdk:17-jdk-slim
2+
3+
WORKDIR /app
4+
5+
COPY build/libs/playground-all.jar /app/playground-all.jar
6+
7+
CMD ["java", "-jar", "playground-all.jar"]

‎playground/README.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Fabrikt Playground
2+
3+
The Fabrikt Playground is a web based tools that allows you to play around with
4+
Fabrikt without installing it locally.
5+
6+
The goal is to make lower the barrier for trying out Fabrikt and to hopefully prove to
7+
people that Fabrikt can be a useful tool for the user and encourage them to embed it in
8+
their development workflow either via the CLI or via Gradle/Maven.
9+
10+
## Technical Details
11+
12+
The playground is built with these amazing Open Source libraries ♥️
13+
* [Ktor](https://github.com/ktorio/ktor) for HTTP
14+
* [kotlinx.html](https://github.com/Kotlin/kotlinx.html) for HTML without writing HTML
15+
* [htmx](https://github.com/bigskysoftware/htmx) for interactivity
16+
* [PrismJS](https://github.com/PrismJS/prism) for syntax highlighting
17+
* [Ace Editor](https://github.com/ajaxorg/ace) for YAML editing
18+
* [Normalize.css](https://github.com/necolas/normalize.css) for default styling
19+
* [BassCSS](https://basscss.com/) for utility CSS
20+
21+
## Building and Deploying
22+
23+
1. Build the jar
24+
```shell
25+
gradle :playground:shadowJar
26+
```
27+
28+
2. Build the Docker image
29+
30+
```shell
31+
docker build -t fabrikt-playground .
32+
```
33+
34+
3. Deploy to the PaaS of choice :rocket:

‎playground/build.gradle.kts

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
plugins {
2+
application
3+
kotlin("jvm")
4+
id("com.github.johnrengelman.shadow") version "8.1.1"
5+
id("com.palantir.git-version") version "3.0.0"
6+
}
7+
8+
application {
9+
mainClass.set("PlaygroundApplicationKt")
10+
applicationDefaultJvmArgs = listOf("-Dio.ktor.development=true")
11+
}
12+
13+
repositories {
14+
mavenCentral()
15+
}
16+
17+
val ktorVersion: String by rootProject.extra
18+
19+
dependencies {
20+
implementation(project(":"))
21+
22+
// ktor server
23+
implementation("io.ktor:ktor-server-netty-jvm:$ktorVersion")
24+
implementation("io.ktor:ktor-server-content-negotiation-jvm:$ktorVersion")
25+
implementation("io.ktor:ktor-server-html-builder:$ktorVersion")
26+
implementation("io.ktor:ktor-server-call-logging:$ktorVersion")
27+
28+
// logging
29+
implementation("ch.qos.logback:logback-classic:1.5.6")
30+
31+
implementation("com.squareup:kotlinpoet:1.14.2") { exclude(module = "kotlin-stdlib-jre7") }
32+
33+
testImplementation(kotlin("test"))
34+
}
35+
36+
tasks.test {
37+
useJUnitPlatform()
38+
dependsOn("shadowJar")
39+
}
40+
41+
kotlin {
42+
jvmToolchain(17)
43+
}
44+
45+
tasks.withType<Jar> {
46+
manifest {
47+
attributes["Main-Class"] = "PlaygroundApplicationKt"
48+
}
49+
}
50+
51+
tasks.withType<CreateStartScripts> {
52+
dependsOn(tasks.shadowJar)
53+
}
54+
55+
tasks.named("shadowJar") {
56+
dependsOn(":shadowJar")
57+
}
58+
59+
val gitVersion: groovy.lang.Closure<*> by extra
60+
version = gitVersion.call()
61+
62+
val generatedDir = layout.buildDirectory.dir("generated/version")
63+
64+
tasks.register("generateVersionFile") {
65+
val versionCode = gitVersion.call().toString()
66+
val outputDir = generatedDir.get().asFile
67+
inputs.property("gitVersion", versionCode)
68+
outputs.dir(outputDir)
69+
doLast {
70+
val file = outputDir.resolve("Version.kt")
71+
file.parentFile.mkdirs()
72+
file.writeText(
73+
"""
74+
object Version {
75+
const val GIT_VERSION = "$versionCode"
76+
}
77+
""".trimIndent()
78+
)
79+
}
80+
}
81+
82+
sourceSets {
83+
main {
84+
java.srcDir(generatedDir)
85+
}
86+
}
87+
88+
tasks.named("compileKotlin") {
89+
dependsOn("generateVersionFile")
90+
}
91+
92+
tasks.named("shadowJar", com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar::class) {
93+
archiveBaseName.set("playground")
94+
archiveClassifier.set("all")
95+
archiveVersion.set("")
96+
}

‎playground/fly.toml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# fly.toml app configuration file generated for fabrikt on 2025-01-10T13:45:20+01:00
2+
#
3+
# See https://fly.io/docs/reference/configuration/ for information about how to use this file.
4+
#
5+
6+
app = 'fabrikt' # --> https://fabrikt.fly.dev
7+
primary_region = 'ams'
8+
9+
[build]
10+
11+
[http_service]
12+
internal_port = 8080
13+
force_https = true
14+
auto_stop_machines = 'suspend'
15+
auto_start_machines = true
16+
min_machines_running = 0
17+
processes = ['app']
18+
19+
[[vm]]
20+
memory = '512mb'
21+
cpu_kind = 'shared'
22+
cpus = 1

0 commit comments

Comments
 (0)