Skip to content
This repository was archived by the owner on Dec 19, 2023. It is now read-only.

Commit f180334

Browse files
fbenzfbenz
authored
Initial Kotlin support (#210)
* Initial Kotlin support * Simplify sentence
1 parent 154df15 commit f180334

File tree

19 files changed

+1059
-2
lines changed

19 files changed

+1059
-2
lines changed

‎pom.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
<module>spring-auto-restdocs-core</module>
1818
<module>spring-auto-restdocs-example</module>
1919
<module>spring-auto-restdocs-docs</module>
20+
<module>spring-auto-restdocs-dokka-json</module>
2021
</modules>
2122

2223
<organization>
@@ -126,6 +127,8 @@
126127
<roots>
127128
<root>src/main/java</root>
128129
<root>src/test/java</root>
130+
<root>src/main/kotlin</root>
131+
<root>src/test/kotlin</root>
129132
</roots>
130133
</configuration>
131134
<executions>

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/jackson/FieldDocumentationObjectVisitor.java‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77
* Licensed under the Apache License, Version 2.0 (the "License");
88
* you may not use this file except in compliance with the License.
99
* You may obtain a copy of the License at
10-
*
10+
*
1111
* http://www.apache.org/licenses/LICENSE-2.0
12-
*
12+
*
1313
* Unless required by applicable law or agreed to in writing, software
1414
* distributed under the License is distributed on an "AS IS" BASIS,
1515
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -51,6 +51,11 @@ public FieldDocumentationObjectVisitor(SerializerProvider provider,
5151
this.typeFactory = typeFactory;
5252
}
5353

54+
@Override
55+
public void property(BeanProperty prop) throws JsonMappingException {
56+
optionalProperty(prop);
57+
}
58+
5459
@Override
5560
public void optionalProperty(BeanProperty prop) throws JsonMappingException {
5661
String jsonName = prop.getName();

‎spring-auto-restdocs-dokka-json/.gitignore‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Compiled class file
2+
*.class
3+
4+
# Log file
5+
*.log
6+
7+
# BlueJ files
8+
*.ctxt
9+
10+
# Mobile Tools for Java (J2ME)
11+
.mtj.tmp/
12+
13+
# Package Files #
14+
*.jar
15+
*.war
16+
*.ear
17+
*.zip
18+
*.tar.gz
19+
*.rar
20+
21+
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
22+
hs_err_pid*
23+
24+
# IntelliJ
25+
.idea/
26+
*.iml
27+
28+
# Genertaed files
29+
target/

‎spring-auto-restdocs-dokka-json/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# KDoc and Javadoc to JSON converter for Spring Auto REST Docs
2+
3+
This library is a [Dokka](https://github.com/Kotlin/dokka) extension.
4+
Dokka is a documentation engine for Kotlin, performing the same function as Javadoc for Java.
5+
Mixed-language Java/Kotlin projects are fully supported.
6+
Dokka understands standard Javadoc comments in Java files and KDoc comments in Kotlin files.
7+
The same holds true for this Dokka extension.
8+
9+
## Usage with Maven
10+
11+
This Dokka extension can be used with the standard `dokka-maven-plugin`.
12+
To avoid any incompatibilities, the Dokka version of the `dokka-maven-plugin` and of this extension should be the same.
13+
If this extension is included as a dependency of the plugin, the output format `auto-restdocs-json` can be used.
14+
15+
Example usage:
16+
```
17+
<plugin>
18+
<groupId>org.jetbrains.dokka</groupId>
19+
<artifactId>dokka-maven-plugin</artifactId>
20+
<version>${dokka.version}</version>
21+
<executions>
22+
<execution>
23+
<phase>compile</phase>
24+
<goals>
25+
<goal>dokka</goal>
26+
</goals>
27+
</execution>
28+
</executions>
29+
<dependencies>
30+
<dependency>
31+
<groupId>capital.scalable</groupId>
32+
<artifactId>spring-auto-restdocs-dokka-json</artifactId>
33+
<version>${spring-auto-restdocs-dokka-json.version}</version>
34+
</dependency>
35+
</dependencies>
36+
<configuration>
37+
<outputFormat>auto-restdocs-json</outputFormat>
38+
<outputDir>${jsonDirectory}</outputDir>
39+
</configuration>
40+
</plugin>
41+
```
42+

‎spring-auto-restdocs-dokka-json/pom.xml‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>capital.scalable</groupId>
7+
<artifactId>spring-auto-restdocs-parent</artifactId>
8+
<version>1.0.12-SNAPSHOT</version>
9+
<relativePath>..</relativePath>
10+
</parent>
11+
12+
<artifactId>spring-auto-restdocs-dokka-json</artifactId>
13+
<packaging>jar</packaging>
14+
15+
<name>Spring Auto REST Docs Dokka JSON</name>
16+
<description>Dokka extension that produces Spring Auto REST Docs' JSON format</description>
17+
<url>https://github.com/scacap/spring-auto-restdocs</url>
18+
19+
<properties>
20+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
21+
<kotlin.version>1.2.30</kotlin.version>
22+
<junit.version>4.12</junit.version>
23+
</properties>
24+
25+
<dependencies>
26+
<dependency>
27+
<groupId>org.jetbrains.kotlin</groupId>
28+
<artifactId>kotlin-stdlib</artifactId>
29+
<version>${kotlin.version}</version>
30+
</dependency>
31+
<dependency>
32+
<groupId>org.jetbrains.kotlin</groupId>
33+
<artifactId>kotlin-test-junit</artifactId>
34+
<version>${kotlin.version}</version>
35+
<scope>test</scope>
36+
</dependency>
37+
<dependency>
38+
<groupId>junit</groupId>
39+
<artifactId>junit</artifactId>
40+
<version>${junit.version}</version>
41+
<scope>test</scope>
42+
</dependency>
43+
<dependency>
44+
<groupId>org.jetbrains.dokka</groupId>
45+
<artifactId>dokka-fatjar</artifactId>
46+
<version>0.9.16</version>
47+
</dependency>
48+
<dependency>
49+
<groupId>com.fasterxml.jackson.core</groupId>
50+
<artifactId>jackson-core</artifactId>
51+
<version>2.9.4</version>
52+
</dependency>
53+
<dependency>
54+
<groupId>com.fasterxml.jackson.module</groupId>
55+
<artifactId>jackson-module-kotlin</artifactId>
56+
<version>2.9.4.1</version>
57+
</dependency>
58+
</dependencies>
59+
60+
<build>
61+
<sourceDirectory>src/main/kotlin</sourceDirectory>
62+
<testSourceDirectory>src/test/kotlin</testSourceDirectory>
63+
64+
<plugins>
65+
<plugin>
66+
<groupId>org.jetbrains.kotlin</groupId>
67+
<artifactId>kotlin-maven-plugin</artifactId>
68+
<version>${kotlin.version}</version>
69+
<executions>
70+
<execution>
71+
<id>compile</id>
72+
<phase>compile</phase>
73+
<goals>
74+
<goal>compile</goal>
75+
</goals>
76+
</execution>
77+
<execution>
78+
<id>test-compile</id>
79+
<phase>test-compile</phase>
80+
<goals>
81+
<goal>test-compile</goal>
82+
</goals>
83+
</execution>
84+
</executions>
85+
</plugin>
86+
</plugins>
87+
</build>
88+
89+
<repositories>
90+
<repository>
91+
<id>jcenter</id>
92+
<url>https://jcenter.bintray.com/</url>
93+
</repository>
94+
</repositories>
95+
96+
</project>

‎spring-auto-restdocs-dokka-json/src/main/kotlin/capital/scalable/dokka/json/JsonFileGenerator.kt‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
/*-
2+
* #%L
3+
* Spring Auto REST Docs Dokka JSON
4+
* %%
5+
* Copyright (C) 2015 - 2018 Scalable Capital GmbH
6+
* %%
7+
* Licensed under the Apache License, Version 2.0 (the "License");
8+
* you may not use this file except in compliance with the License.
9+
* You may obtain a copy of the License at
10+
*
11+
* http://www.apache.org/licenses/LICENSE-2.0
12+
*
13+
* Unless required by applicable law or agreed to in writing, software
14+
* distributed under the License is distributed on an "AS IS" BASIS,
15+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* See the License for the specific language governing permissions and
17+
* limitations under the License.
18+
* #L%
19+
*/
20+
package capital.scalable.dokka.json
21+
22+
import com.google.inject.Inject
23+
import org.jetbrains.dokka.*
24+
import java.io.File
25+
import java.io.FileOutputStream
26+
import java.io.IOException
27+
import java.io.OutputStreamWriter
28+
29+
class JsonFileGenerator @Inject constructor(val locationService: FileLocationService) : Generator {
30+
31+
@set:Inject(optional = true)
32+
lateinit var formatService: FormatService
33+
34+
override fun buildPages(nodes: Iterable<DocumentationNode>) {
35+
val specificLocationService = locationService.withExtension(formatService.extension)
36+
37+
for ((_, items) in nodes.groupBy { specificLocationService.location(it) }) {
38+
if (items.any { it.kind == NodeKind.Class }) {
39+
val location = locationOverride(items.find { it.kind == NodeKind.Class }!!)
40+
val file = location.file
41+
file.parentFile?.mkdirsOrFail()
42+
try {
43+
FileOutputStream(file).use {
44+
OutputStreamWriter(it, Charsets.UTF_8).use {
45+
it.write(formatService.format(location, items))
46+
}
47+
}
48+
} catch (e: Throwable) {
49+
println(e)
50+
}
51+
}
52+
buildPages(items.flatMap { it.members })
53+
}
54+
}
55+
56+
private fun locationOverride(node: DocumentationNode): FileLocation {
57+
val path = node.path
58+
// Remove class name. It is appended again below.
59+
.dropLast(1)
60+
.filter { it.name.isNotEmpty() && it.kind != NodeKind.Module }
61+
.joinToString("") {
62+
if (it.kind == NodeKind.Class) {
63+
// Parent class if the node is a nested class
64+
"${it.name}."
65+
} else {
66+
// Turn package dots into folders
67+
"${it.name.replace(".", "/")}/"
68+
}
69+
}
70+
val className = node.name
71+
return FileLocation(File(locationService.root.path, "$path$className.json"))
72+
}
73+
74+
override fun buildOutlines(nodes: Iterable<DocumentationNode>) {}
75+
76+
override fun buildSupportFiles() {}
77+
78+
override fun buildPackageList(nodes: Iterable<DocumentationNode>) {}
79+
80+
private fun File.mkdirsOrFail() {
81+
if (!mkdirs() && !exists()) {
82+
throw IOException("Failed to create directory $this")
83+
}
84+
}
85+
}

‎spring-auto-restdocs-dokka-json/src/main/kotlin/capital/scalable/dokka/json/JsonFormatDescriptor.kt‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
/*-
2+
* #%L
3+
* Spring Auto REST Docs Dokka JSON
4+
* %%
5+
* Copyright (C) 2015 - 2018 Scalable Capital GmbH
6+
* %%
7+
* Licensed under the Apache License, Version 2.0 (the "License");
8+
* you may not use this file except in compliance with the License.
9+
* You may obtain a copy of the License at
10+
*
11+
* http://www.apache.org/licenses/LICENSE-2.0
12+
*
13+
* Unless required by applicable law or agreed to in writing, software
14+
* distributed under the License is distributed on an "AS IS" BASIS,
15+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* See the License for the specific language governing permissions and
17+
* limitations under the License.
18+
* #L%
19+
*/
20+
package capital.scalable.dokka.json
21+
22+
import org.jetbrains.dokka.*
23+
import org.jetbrains.dokka.Formats.FormatDescriptor
24+
import org.jetbrains.dokka.Kotlin.KotlinDescriptorSignatureProvider
25+
import org.jetbrains.dokka.Samples.DefaultSampleProcessingService
26+
import org.jetbrains.dokka.Samples.SampleProcessingService
27+
import kotlin.reflect.KClass
28+
29+
class JsonFormatDescriptor : FormatDescriptor {
30+
override val formatServiceClass = JsonFormatService::class
31+
32+
override val packageDocumentationBuilderClass = KotlinPackageDocumentationBuilder::class
33+
override val javaDocumentationBuilderClass = KotlinJavaDocumentationBuilder::class
34+
35+
override val generatorServiceClass = JsonFileGenerator::class
36+
override val outlineServiceClass: KClass<out OutlineFormatService>? = null
37+
override val sampleProcessingService: KClass<out SampleProcessingService> = DefaultSampleProcessingService::class
38+
override val packageListServiceClass: KClass<out PackageListService>? = DefaultPackageListService::class
39+
override val descriptorSignatureProvider = KotlinDescriptorSignatureProvider::class
40+
}

0 commit comments

Comments
 (0)