Skip to content

Commit 2c7cf24

Browse files
jknackjknack
committed
OpenAPI: checkstyle appliance
1 parent 7f3385e commit 2c7cf24

9 files changed

Lines changed: 479 additions & 101 deletions

File tree

‎jooby/src/main/java/io/jooby/OpenAPIModule.java‎

Lines changed: 71 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,40 @@
1717
import java.util.Map;
1818
import java.util.Optional;
1919

20+
/**
21+
* OpenAPI supports for Jooby. Basic Usage:
22+
*
23+
* <pre>{@code
24+
* {
25+
* install(new OpenAPIModule());
26+
* }
27+
* }</pre>
28+
*
29+
* The <code>[openapi].json</code> and/or <code>[openapi].yaml</code> files must be present on
30+
* classpath.
31+
*
32+
* If <code>jooby-swagger-ui</code> is present (part of your project classpath) swagger-ui will
33+
* be available. Same for <code>jooby-redoc</code>.
34+
*
35+
* Complete documentation is available at: https://jooby.io/modules/openapi
36+
*
37+
* @author edgar
38+
* @since 2.7.0
39+
*/
2040
public class OpenAPIModule implements Extension {
2141

42+
/**
43+
* Available formats.
44+
*/
2245
public enum Format {
46+
/**
47+
* JSON.
48+
*/
2349
JSON,
50+
51+
/**
52+
* YAML.
53+
*/
2454
YAML
2555
}
2656

@@ -29,25 +59,61 @@ public enum Format {
2959
private String redocPath = "/redoc";
3060
private EnumSet<Format> format = EnumSet.of(Format.JSON, Format.YAML);
3161

32-
public OpenAPIModule(String path) {
62+
/**
63+
* Creates an OpenAPI module. The path is used to route the open API files. For example:
64+
*
65+
* <pre>{@code
66+
* install(new OpenAPIModule("/docs"));
67+
* }</pre>
68+
*
69+
* Files will be at <code>/docs/openapi.json</code>, <code>/docs/openapi.yaml</code>.
70+
*
71+
* @param path Custom path to use.
72+
*/
73+
public OpenAPIModule(@Nonnull String path) {
3374
this.openAPIPath = Router.normalizePath(path);
3475
}
3576

77+
/**
78+
* Creates an OpenAPI module.
79+
*
80+
* Files will be at <code>/openapi.json</code>, <code>/openapi.yaml</code>.
81+
*/
3682
public OpenAPIModule() {
3783
this("/");
3884
}
3985

40-
public OpenAPIModule swaggerUI(String path) {
86+
/**
87+
* Customize the swagger-ui path. Defaults is <code>/swagger</code>.
88+
*
89+
* @param path Swagger-ui path.
90+
* @return This module.
91+
*/
92+
public @Nonnull OpenAPIModule swaggerUI(@Nonnull String path) {
4193
this.swaggerUIPath = Router.normalizePath(path);
4294
return this;
4395
}
4496

45-
public OpenAPIModule redoc(String path) {
97+
/**
98+
* Customize the redoc-ui path. Defaults is <code>/redoc</code>.
99+
*
100+
* @param path Redoc path.
101+
* @return This module.
102+
*/
103+
public @Nonnull OpenAPIModule redoc(@Nonnull String path) {
46104
this.redocPath = Router.normalizePath(path);
47105
return this;
48106
}
49107

50-
public OpenAPIModule format(Format... format) {
108+
/**
109+
* Enable what format are available (json or yaml).
110+
*
111+
* IMPORTANT: UI tools requires the JSON format.
112+
*
113+
* @param format Supported formats.
114+
* @return This module.
115+
*/
116+
public @Nonnull OpenAPIModule format(@Nonnull Format... format) {
51117
this.format = EnumSet.copyOf(Arrays.asList(format));
52118
return this;
53119
}
@@ -72,7 +138,7 @@ public OpenAPIModule format(Format... format) {
72138
configureUI(application);
73139
}
74140

75-
private void configureUI(@Nonnull Jooby application) {
141+
private void configureUI(Jooby application) {
76142
Map<String, Consumer2<Jooby, AssetSource>> ui = new HashMap<>();
77143
ui.put("swagger-ui", this::swaggerUI);
78144
ui.put("redoc", this::redoc);

‎modules/jooby-gradle-plugin/src/main/java/io/jooby/gradle/BaseTask.java‎

Lines changed: 87 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import org.gradle.api.plugins.JavaPluginConvention;
1212
import org.gradle.api.tasks.SourceSet;
1313

14+
import javax.annotation.Nonnull;
1415
import java.io.File;
1516
import java.net.MalformedURLException;
1617
import java.net.URL;
@@ -26,15 +27,34 @@
2627
import java.util.function.Predicate;
2728
import java.util.stream.Collectors;
2829

30+
/**
31+
* Base class which provides common utility method to more specific plugins: like classpath
32+
* resources.
33+
*
34+
* Also, handle maven specific exceptions.
35+
*
36+
* @author edgar
37+
*/
2938
public class BaseTask extends DefaultTask {
3039

3140
protected static final String APP_CLASS = "mainClassName";
3241

33-
public List<Project> getProjects() {
42+
/**
43+
* Available projects.
44+
*
45+
* @return Available projects.
46+
*/
47+
public @Nonnull List<Project> getProjects() {
3448
return Collections.singletonList(getProject());
3549
}
3650

37-
protected String computeMainClassName(List<Project> projects) {
51+
/**
52+
* Compute class name from available projects.
53+
*
54+
* @param projects Projects.
55+
* @return Main class.
56+
*/
57+
protected @Nonnull String computeMainClassName(@Nonnull List<Project> projects) {
3858
return projects.stream()
3959
.filter(it -> it.getProperties().containsKey(APP_CLASS))
4060
.map(it -> it.getProperties().get(APP_CLASS).toString())
@@ -43,24 +63,55 @@ protected String computeMainClassName(List<Project> projects) {
4363
"Application class not found. Did you forget to set `" + APP_CLASS + "`?"));
4464
}
4565

46-
protected Set<Path> binDirectories(Project project, SourceSet sourceSet) {
66+
/**
67+
* Project binary directories.
68+
*
69+
* @param project Project.
70+
* @param sourceSet Source set.
71+
* @return Directories.
72+
*/
73+
protected @Nonnull Set<Path> binDirectories(@Nonnull Project project,
74+
@Nonnull SourceSet sourceSet) {
4775
return classpath(project, sourceSet, it -> Files.exists(it) && Files.isDirectory(it));
4876
}
4977

50-
protected Set<Path> dependencies(Project project, SourceSet sourceSet) {
78+
/**
79+
* Project dependencies(jars).
80+
*
81+
* @param project Project.
82+
* @param sourceSet Source set.
83+
* @return Jar files.
84+
*/
85+
protected @Nonnull Set<Path> dependencies(@Nonnull Project project,
86+
@Nonnull SourceSet sourceSet) {
5187
return classpath(project, sourceSet, it -> Files.exists(it) && it.toString().endsWith(".jar"));
5288
}
5389

54-
protected Path classes(Project project) {
55-
SourceSet sourceSet = sourceSet(project);
90+
/**
91+
* Project classes directory.
92+
*
93+
* @param project Project.
94+
* @return Classes directory.
95+
*/
96+
protected @Nonnull Path classes(@Nonnull Project project) {
97+
SourceSet sourceSet = sourceSet(project);
5698
return sourceSet.getRuntimeClasspath().getFiles().stream()
5799
.filter(f -> f.exists() && f.isDirectory() && f.toString().contains("classes"))
58100
.findFirst()
59101
.get()
60102
.toPath();
61103
}
62104

63-
protected Set<Path> classpath(Project project, SourceSet sourceSet, Predicate<Path> predicate) {
105+
/**
106+
* Project classpath.
107+
*
108+
* @param project Project.
109+
* @param sourceSet Source set.
110+
* @param predicate Path filter.
111+
* @return Classpath.
112+
*/
113+
protected @Nonnull Set<Path> classpath(@Nonnull Project project, @Nonnull SourceSet sourceSet,
114+
@Nonnull Predicate<Path> predicate) {
64115
Set<Path> result = new LinkedHashSet<>();
65116
// classes/main, resources/main + jars
66117
sourceSet.getRuntimeClasspath().getFiles().stream()
@@ -77,7 +128,14 @@ protected Set<Path> classpath(Project project, SourceSet sourceSet, Predicate<Pa
77128
return result;
78129
}
79130

80-
protected Set<Path> sourceDirectories(Project project, SourceSet sourceSet) {
131+
/**
132+
* Project source directories.
133+
*
134+
* @param project Project.
135+
* @param sourceSet Source set.
136+
* @return Source directories.
137+
*/
138+
protected @Nonnull Set<Path> sourceDirectories(@Nonnull Project project, @Nonnull SourceSet sourceSet) {
81139
Path eclipse = project.getProjectDir().toPath().resolve(".classpath");
82140
if (Files.exists(eclipse)) {
83141
// let eclipse to do the incremental compilation
@@ -89,15 +147,34 @@ protected Set<Path> sourceDirectories(Project project, SourceSet sourceSet) {
89147
.collect(Collectors.toCollection(LinkedHashSet::new));
90148
}
91149

92-
protected SourceSet sourceSet(final Project project) {
150+
/**
151+
* Source set.
152+
*
153+
* @param project Project.
154+
* @return SourceSet.
155+
*/
156+
protected @Nonnull SourceSet sourceSet(final @Nonnull Project project) {
93157
return getJavaConvention(project).getSourceSets()
94158
.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
95159
}
96160

97-
protected JavaPluginConvention getJavaConvention(final Project project) {
161+
/**
162+
* Java plugin convention.
163+
*
164+
* @param project Project.
165+
* @return Java plugin convention.
166+
*/
167+
protected @Nonnull JavaPluginConvention getJavaConvention(final @Nonnull Project project) {
98168
return project.getConvention().getPlugin(JavaPluginConvention.class);
99169
}
100170

171+
/**
172+
* Creates a class loader.
173+
*
174+
* @param projects Projects to use.
175+
* @return Class loader.
176+
* @throws MalformedURLException If there is a bad path reference.
177+
*/
101178
protected ClassLoader createClassLoader(List<Project> projects)
102179
throws MalformedURLException {
103180
List<URL> cp = new ArrayList<>();

‎modules/jooby-gradle-plugin/src/main/java/io/jooby/gradle/OpenAPITask.java‎

Lines changed: 53 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,34 @@
1010
import org.gradle.api.Project;
1111
import org.gradle.api.tasks.TaskAction;
1212

13+
import javax.annotation.Nonnull;
14+
import javax.annotation.Nullable;
1315
import java.nio.file.Path;
1416
import java.util.List;
1517
import java.util.Optional;
1618
import java.util.stream.Stream;
1719

20+
/**
21+
* Generate an OpenAPI file from a jooby application.
22+
*
23+
* Usage: https://jooby.io/modules/openapi
24+
*
25+
* @author edgar
26+
* @since 2.7.0
27+
*/
1828
public class OpenAPITask extends BaseTask {
1929

2030
private String mainClassName;
2131

22-
private String format = "json,yaml";
23-
2432
private String includes;
2533

2634
private String excludes;
2735

36+
/**
37+
* Generate OpenAPI files from Jooby application.
38+
*
39+
* @throws Throwable If something goes wrong.
40+
*/
2841
@TaskAction
2942
public void generate() throws Throwable {
3043
List<Project> projects = getProjects();
@@ -51,40 +64,62 @@ public void generate() throws Throwable {
5164

5265
OpenAPI result = tool.generate(mainClass);
5366

54-
for (OpenAPIGenerator.Format format : OpenAPIGenerator.Format.parse(format)) {
55-
tool.export(result, format);
67+
for (OpenAPIGenerator.Format format : OpenAPIGenerator.Format.values()) {
68+
Path output = tool.export(result, format);
69+
getLogger().info(" writing: " + output);
5670
}
5771
}
5872

59-
public String getMainClassName() {
73+
/**
74+
* Class to parse.
75+
*
76+
* @return Class to parse.
77+
*/
78+
public @Nonnull String getMainClassName() {
6079
return mainClassName;
6180
}
6281

63-
public void setMainClassName(String mainClassName) {
82+
/**
83+
* Set Class to parse.
84+
* @param mainClassName Class to parse.
85+
*/
86+
public void setMainClassName(@Nonnull String mainClassName) {
6487
this.mainClassName = mainClassName;
6588
}
6689

67-
public String getFormat() {
68-
return format;
69-
}
70-
71-
public void setFormat(String format) {
72-
this.format = format;
73-
}
74-
75-
public String getIncludes() {
90+
/**
91+
* Regular expression used to includes/keep route. Example: <code>/api/.*</code>.
92+
*
93+
* @return Regular expression used to includes/keep route. Example: <code>/api/.*</code>.
94+
*/
95+
public @Nullable String getIncludes() {
7696
return includes;
7797
}
7898

79-
public void setIncludes(String includes) {
99+
/**
100+
* Set regular expression used to includes/keep route. Example: <code>/api/.*</code>.
101+
*
102+
* @param includes Regular expression.
103+
*/
104+
public void setIncludes(@Nullable String includes) {
80105
this.includes = includes;
81106
}
82107

83-
public String getExcludes() {
108+
/**
109+
* Regular expression used to excludes route. Example: <code>/web</code>.
110+
*
111+
* @return Regular expression used to excludes route. Example: <code>/web</code>.
112+
*/
113+
public @Nullable String getExcludes() {
84114
return excludes;
85115
}
86116

87-
public void setExcludes(String excludes) {
117+
/**
118+
* Set Regular expression used to excludes route. Example: <code>/web</code>.
119+
*
120+
* @param excludes Regular expression used to excludes route. Example: <code>/web</code>.
121+
*/
122+
public void setExcludes(@Nullable String excludes) {
88123
this.excludes = excludes;
89124
}
90125

0 commit comments

Comments
 (0)