Skip to content

Commit 3cb93b6

Browse files
cortinicocortinico
authored
Adding some examples of generated code (#12)
* Add an example of generated code * Updated README with some samples * Updated examples to use petstore * Include @olivierperez suggestions in the README * Make sure Matespace is big enough * Fixed broken link in README file * Rephrased the Example section * Make sure the specs inside SAMPLES.md are valid
1 parent 78eeae0 commit 3cb93b6

20 files changed

+889
-8
lines changed

‎README.md‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,20 @@ Here the list of the supported platforms:
6363

6464
We're looking forward to more platforms to support in the future. Contributions are more than welcome.
6565

66+
## Examples
67+
68+
You can find some **examples** in this repository to help you set up your generator environment.
69+
70+
* [sample-generated-code](/sample-generated-code) Contains an example of an Android Library where the code is generated inside the `/scr/main/java` folder. You can use this example to see how the generated code will _look like_ (like [here](/sample-generated-code/src/main/java/com/yelp/codegen/generatecodesamples/apis/DefaultApi.kt))
71+
72+
* [sample-groovy-android](/sample-groovy-android) Contains an example of an Android Library configured with a `build.gradle` file, using the classical Gradle/Groovy as scripting language.
73+
74+
* [sample-kotlin-android](/sample-kotlin-android) Contains an example of an Android Library configured with a `build.gradle.kts` file, using Kotlin as scripting language.
75+
76+
## How the generated code will look like
77+
78+
[Here](/SAMPLES.md) you can find some examples of how the generated code will look like in your project.
79+
6680
## Configuration
6781

6882
To configure the generator, please use the `generateSwagger { }` block. Here an example of this block with all the properties.
@@ -109,13 +123,6 @@ Here a list of all the supported features:
109123
| -------- | ----------- | ------------ |
110124
| `headersToRemove` | List of headers that needs to be ignored for every endpoints. The headers in this list will be dropped and not generated as parameters for the endpoints. | `--featureHeaderToRemove=` |
111125

112-
## Examples
113-
114-
You can find some **examples** in this repository to help you set up your generator environment.
115-
116-
* [sample-groovy-android](/sample-groovy-android) Contains an example of an Android Library configured with a `build.gradle` file, using Groovy as scripting language.
117-
118-
* [sample-kotlin-android](/sample-kotlin-android) Contains an example of an Android Library configured with a `build.gradle.kts` file, using Kotlin as scripting language.
119126

120127
## Building
121128

‎SAMPLES.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
In this page you can find some samples of generated code using swagger-gradle-codegen for every platform:
2+
3+
## `kotlin` platform
4+
5+
The following specs:
6+
7+
```json
8+
{
9+
"definitions": {
10+
"Category": {
11+
"description": "A Category used to group pets",
12+
"properties": {
13+
"id": {
14+
"description": "Unique ID of the Category",
15+
"format": "int64",
16+
"type": "integer"
17+
},
18+
"name": {
19+
"description": "Name of this category",
20+
"type": "string"
21+
}
22+
},
23+
"type": "object"
24+
},
25+
"Pet": {
26+
"description": "Represents a specific Pet in the store",
27+
"properties": {
28+
"category": {
29+
"$ref": "#/definitions/Category",
30+
"description": "Optional category of the pet"
31+
},
32+
"id": {
33+
"description": "Unique ID of this Pet",
34+
"format": "int64",
35+
"type": "integer"
36+
},
37+
"name": {
38+
"description": "Name of this specific pet",
39+
"type": "string"
40+
},
41+
"photoUrls": {
42+
"description": "Photo URls for this Pet on the bucket",
43+
"items": {
44+
"type": "string"
45+
},
46+
"type": "array"
47+
},
48+
"tags": {
49+
"description": "Pet status in the store",
50+
"items": {
51+
"$ref": "#/definitions/Tag"
52+
},
53+
"type": "array"
54+
}
55+
},
56+
"required": [
57+
"name",
58+
"photoUrls"
59+
],
60+
"type": "object"
61+
},
62+
"Tag": {
63+
"description": "A Tag used to group entities",
64+
"properties": {
65+
"id": {
66+
"description": "Unique ID of the Tag",
67+
"format": "int64",
68+
"type": "integer"
69+
},
70+
"name": {
71+
"description": "Name of this Tag",
72+
"type": "string"
73+
}
74+
},
75+
"type": "object"
76+
}
77+
},
78+
"info": {
79+
"description": "This is a simplified version of the sample server Petstore server.",
80+
"title": "Swagger Petstore",
81+
"version": "1.0.0"
82+
},
83+
"paths": {
84+
"/pet/{petId}": {
85+
"get": {
86+
"description": "Returns a single pet",
87+
"operationId": "getPetById",
88+
"parameters": [
89+
{
90+
"description": "ID of pet to return",
91+
"format": "int64",
92+
"in": "path",
93+
"name": "petId",
94+
"required": true,
95+
"type": "integer"
96+
}
97+
],
98+
"responses": {
99+
"200": {
100+
"description": "successful operation",
101+
"schema": {
102+
"$ref": "#/definitions/Pet"
103+
}
104+
}
105+
},
106+
"summary": "Find pet by ID"
107+
}
108+
}
109+
},
110+
"swagger": "2.0"
111+
}
112+
```
113+
114+
Will generate the following Retrofit Interfaces and Kotlin Data Classes:
115+
116+
### DefaultApi.kt
117+
118+
`DefaultApi.kt` will contain a Retrofit interface with all the endpoints, in this case just one:
119+
120+
```kotlin
121+
/**
122+
* NOTE: This class is auto generated by the Swagger Gradle Codegen for the following API: Swagger Petstore
123+
*
124+
* More info on this tool is available on https://github.com/Yelp/swagger-gradle-codegen
125+
*/
126+
127+
package com.yelp.codegen.generatecodesamples.apis
128+
129+
import com.yelp.codegen.generatecodesamples.models.Pet
130+
import io.reactivex.Single
131+
import retrofit2.http.GET
132+
import retrofit2.http.Headers
133+
134+
@JvmSuppressWildcards
135+
interface DefaultApi {
136+
/**
137+
* Find pet by ID
138+
* Returns a single pet
139+
* The endpoint is owned by generatecodesamples service owner
140+
* @param petId ID of pet to return (required)
141+
*/
142+
@Headers(
143+
"X-Operation-ID: getPetById"
144+
)
145+
@GET("/pet/{petId}")
146+
fun getPetById(
147+
@retrofit2.http.Path("petId") petId: Long
148+
): Single<Pet>
149+
}
150+
```
151+
152+
### Pets.kt
153+
154+
`Pets.kt` will contain a Kotlin Data class that will be used as response type for the `/pet/{petID}` endpoint.
155+
156+
Other classes are generated as well (`Category` & `Tag`). They're omitted for brevity but they're available inside [this folder](/sample-generated-code/src/main/java/com/yelp/codegen/generatecodesamples/models).
157+
158+
```kotlin
159+
/**
160+
* NOTE: This class is auto generated by the Swagger Gradle Codegen for the following API: Swagger Petstore
161+
*
162+
* More info on this tool is available on https://github.com/Yelp/swagger-gradle-codegen
163+
*/
164+
165+
package com.yelp.codegen.generatecodesamples.models
166+
167+
import com.squareup.moshi.Json
168+
169+
/**
170+
* Represents a specific Pet in the store
171+
* @property id Unique ID of this Pet
172+
* @property category Optional category of the pet
173+
* @property name Name of this specific pet
174+
* @property photoUrls Photo URls for this Pet on the bucket
175+
* @property tags Pet status in the store
176+
*/
177+
data class Pet(
178+
@Json(name = "name") @field:Json(name = "name") var name: String,
179+
@Json(name = "photoUrls") @field:Json(name = "photoUrls") var photoUrls: List<String>,
180+
@Json(name = "id") @field:Json(name = "id") var id: Long? = null,
181+
@Json(name = "category") @field:Json(name = "category") var category: Category? = null,
182+
@Json(name = "tags") @field:Json(name = "tags") var tags: List<Tag>? = null
183+
)
184+
```

‎gradle.properties‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=4g

‎sample-generated-code/build.gradle‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
buildscript {
2+
repositories {
3+
mavenLocal()
4+
gradlePluginPortal()
5+
google()
6+
mavenCentral()
7+
jcenter()
8+
}
9+
10+
dependencies {
11+
classpath "com.android.tools.build:gradle:3.2.1"
12+
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.3.21"
13+
classpath "com.yelp.codegen:plugin:1.0.0"
14+
}
15+
}
16+
17+
apply plugin: "com.android.library"
18+
apply plugin: "kotlin-android"
19+
apply plugin: "com.yelp.codegen.plugin"
20+
21+
android {
22+
compileSdkVersion = 28
23+
defaultConfig {
24+
minSdkVersion 21
25+
targetSdkVersion 28
26+
versionCode = 1
27+
versionName = "1.0"
28+
}
29+
}
30+
31+
dependencies {
32+
// Kotlin
33+
implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.21"
34+
implementation "org.jetbrains.kotlin:kotlin-reflect:1.3.21"
35+
36+
// Moshi
37+
implementation "com.squareup.moshi:moshi:1.8.0"
38+
implementation "com.squareup.moshi:moshi-adapters:1.8.0"
39+
implementation "com.squareup.moshi:moshi-kotlin:1.8.0"
40+
implementation "com.squareup.retrofit2:converter-moshi:2.5.0"
41+
42+
// Date Support
43+
implementation "com.jakewharton.threetenabp:threetenabp:1.1.1"
44+
45+
// RxJava
46+
implementation "io.reactivex.rxjava2:rxjava:2.2.4"
47+
implementation "io.reactivex.rxjava2:rxandroid:2.1.0"
48+
}
49+
50+
generateSwagger {
51+
platform = "kotlin"
52+
packageName = "com.yelp.codegen.generatecodesamples"
53+
specName = "generatecodesamples"
54+
inputFile = file("./simplified_pet_store.json")
55+
outputDir = file("./src/main/java/")
56+
features {
57+
headersToRemove = ["Accept-Language"]
58+
}
59+
}
60+
61+
repositories {
62+
mavenCentral()
63+
}

‎sample-generated-code/simplified_pet_store.json‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
{
2+
"definitions": {
3+
"Category": {
4+
"description": "A Category used to group pets",
5+
"properties": {
6+
"id": {
7+
"description": "Unique ID of the Category",
8+
"format": "int64",
9+
"type": "integer"
10+
},
11+
"name": {
12+
"description": "Name of this category",
13+
"type": "string"
14+
}
15+
},
16+
"type": "object"
17+
},
18+
"Pet": {
19+
"description": "Represents a specific Pet in the store",
20+
"properties": {
21+
"category": {
22+
"$ref": "#/definitions/Category",
23+
"description": "Optional category of the pet"
24+
},
25+
"id": {
26+
"description": "Unique ID of this Pet",
27+
"format": "int64",
28+
"type": "integer"
29+
},
30+
"name": {
31+
"description": "Name of this specific pet",
32+
"type": "string"
33+
},
34+
"photoUrls": {
35+
"description": "Photo URls for this Pet on the bucket",
36+
"items": {
37+
"type": "string"
38+
},
39+
"type": "array"
40+
},
41+
"tags": {
42+
"description": "Pet status in the store",
43+
"items": {
44+
"$ref": "#/definitions/Tag"
45+
},
46+
"type": "array"
47+
}
48+
},
49+
"required": [
50+
"name",
51+
"photoUrls"
52+
],
53+
"type": "object"
54+
},
55+
"Tag": {
56+
"description": "A Tag used to group entities",
57+
"properties": {
58+
"id": {
59+
"description": "Unique ID of the Tag",
60+
"format": "int64",
61+
"type": "integer"
62+
},
63+
"name": {
64+
"description": "Name of this Tag",
65+
"type": "string"
66+
}
67+
},
68+
"type": "object"
69+
}
70+
},
71+
"info": {
72+
"description": "This is a simplified version of the sample server Petstore server.",
73+
"title": "Swagger Petstore",
74+
"version": "1.0.0"
75+
},
76+
"paths": {
77+
"/pet/{petId}": {
78+
"get": {
79+
"description": "Returns a single pet",
80+
"operationId": "getPetById",
81+
"parameters": [
82+
{
83+
"description": "ID of pet to return",
84+
"format": "int64",
85+
"in": "path",
86+
"name": "petId",
87+
"required": true,
88+
"type": "integer"
89+
}
90+
],
91+
"responses": {
92+
"200": {
93+
"description": "successful operation",
94+
"schema": {
95+
"$ref": "#/definitions/Pet"
96+
}
97+
}
98+
},
99+
"summary": "Find pet by ID"
100+
}
101+
}
102+
},
103+
"swagger": "2.0"
104+
}

‎sample-generated-code/src/main/AndroidManifest.xml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
2+
package="com.yelp.samplelibrary"/>

0 commit comments

Comments
 (0)