Skip to content

complement: persist openapi specification #3983

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jknack wants to merge 1 commit into
base: main
Choose a base branch
from
Open

complement: persist openapi specification #3983

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 19 additions & 15 deletions docs/asciidoc/modules/openapi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,25 @@ To avoid this behaviour you can specify maven build phase which suits your needs
| `${project.dir}`
|Set base directory used it for loading openAPI template file name.

|`copyOpenApiSpecTo`
|
|Copy the generated OpenAPI spec to the given file in the project repository. It must be one or
more directories or file names. In case of directory both the `.json` and `.yaml` file are copy.
Example:

.Maven:

<copyOpenApiSpecTo>
<file>${project.basedir}/spec<file>
<file>${project.basedir}/docs/openapi.yaml<file>
</copyOpenApiSpecTo>

.Gradle:

{
copyOpenApiSpecTo = ["${project.basedir}/spec", "$projectDir/docs/openapi.yaml"]
}

|`excludes`
|
|Regular expression used to excludes route. Example: `/web`.
Expand All @@ -128,21 +147,6 @@ To avoid this behaviour you can specify maven build phase which suits your needs
|`openapi.yaml`
|Set openAPI template file path.

|`copyOpenApiSpecTo`
|
|Copy the generated OpenAPI spec to the given file in the project repository. The format is
determined by the file extension: `.yaml`, `.yml` or `.json`. Example:

.Maven:

<copyOpenApiSpecTo>${project.basedir}/docs/openapi.yaml</copyOpenApiSpecTo>

.Gradle:

{
copyOpenApiSpecTo = file("$projectDir/docs/openapi.yaml")
}

|===

=== Usage
Expand Down
67 changes: 10 additions & 57 deletions modules/jooby-gradle-plugin/src/main/java/io/jooby/gradle/OpenAPITask.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ public class OpenAPITask extends BaseTask {

private String javadoc;

private File copyOpenApiSpecTo;
private List<File> copyOpenApiSpecTo;

/**
* Creates an OpenAPI task.
Expand Down Expand Up @@ -89,6 +89,7 @@ public void generate() throws Throwable {
tool.setClassLoader(classLoader);
tool.setOutputDir(outputDir);
tool.setSources(sources);
tool.setCopyOpenApiSpecTo(copyOpenApiSpecTo == null ? null : copyOpenApiSpecTo.stream().map(File::toPath).toList());
if (specVersion != null) {
tool.setSpecVersion(specVersion);
}
Expand All @@ -101,48 +102,10 @@ public void generate() throws Throwable {
OpenAPI result = tool.generate(mainClass);

var adocPath = ofNullable(adoc).orElse(List.of()).stream().map(File::toPath).toList();
var written = new ArrayList<Path>();
for (var format : OpenAPIGenerator.Format.values()) {
written.addAll(tool.export(result, format, Map.of("adoc", adocPath)));
tool.export(result, format, Map.of("adoc", adocPath))
.forEach(output -> getLogger().info(" writing: " + output));
}
written.forEach(output -> getLogger().info(" writing: " + output));

if (copyOpenApiSpecTo != null) {
var destination = copyOpenApiSpecTo.toPath();
copySpec(written, destination);
getLogger().info(" copying: " + destination);
}
}

static void copySpec(List<Path> written, Path destination) throws IOException {
var format = specFormat(destination);
var source =
written.stream()
.filter(path -> path.getFileName().toString().endsWith("." + format.extension()))
.findFirst()
.orElseThrow(
() ->
new IOException(
String.format(
"OpenAPI %s output not found for copyOpenApiSpecTo: %s",
format.name(), destination)));
var parent = destination.getParent();
if (parent != null) {
Files.createDirectories(parent);
}
Files.copy(source, destination, StandardCopyOption.REPLACE_EXISTING);
}

static OpenAPIGenerator.Format specFormat(Path destination) {
var name = destination.getFileName().toString().toLowerCase(Locale.ROOT);
if (name.endsWith(".json")) {
return OpenAPIGenerator.Format.JSON;
}
if (name.endsWith(".yaml") || name.endsWith(".yml")) {
return OpenAPIGenerator.Format.YAML;
}
throw new IllegalArgumentException(
"copyOpenApiSpecTo must end with .yaml, .yml or .json: " + destination);
}

/**
Expand Down Expand Up @@ -289,32 +252,22 @@ public void setAdoc(List<File> adoc) {
}

/**
* Copy the generated OpenAPI spec to the given file. The format is determined by the file
* extension: <code>.yaml</code>, <code>.yml</code> or <code>.json</code>.
* List directories or files where the openAPI spec must be copied.
*
* @return Destination file.
* @return List directories or files where the openAPI spec must be copied.
*/
@Input
@org.gradle.api.tasks.Optional
public @Nullable File getCopyOpenApiSpecTo() {
public @Nullable List<File> getCopyOpenApiSpecTo() {
return copyOpenApiSpecTo;
}

/**
* Copy the generated OpenAPI spec to the given file. The format is determined by the file
* extension: <code>.yaml</code>, <code>.yml</code> or <code>.json</code>.
*
* <p>Example:
*
* <pre>{@code
* openAPI {
* copyOpenApiSpecTo = file("$projectDir/docs/openapi.yaml")
* }
* }</pre>
* Copy open API files to either an output location or specific file.
*
* @param copyOpenApiSpecTo Destination file.
* @param copyOpenApiSpecTo Output directory or file.
*/
public void setCopyOpenApiSpecTo(@Nullable File copyOpenApiSpecTo) {
public void setCopyOpenApiSpecTo(@Nullable List<File> copyOpenApiSpecTo) {
this.copyOpenApiSpecTo = copyOpenApiSpecTo;
}

Expand Down
56 changes: 7 additions & 49 deletions modules/jooby-maven-plugin/src/main/java/io/jooby/maven/OpenAPIMojo.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,9 @@
import static org.apache.maven.plugins.annotations.ResolutionScope.COMPILE_PLUS_RUNTIME;

import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;

Expand Down Expand Up @@ -58,8 +53,7 @@ public class OpenAPIMojo extends BaseMojo {

@Parameter private List<File> adoc;

@Parameter(property = "openAPI.copyOpenApiSpecTo")
private File copyOpenApiSpecTo;
@Parameter private List<File> copyOpenApiSpecTo;

@Override
protected void doExecute(List<MavenProject> projects, String mainClass) throws Exception {
Expand All @@ -83,6 +77,8 @@ protected void doExecute(List<MavenProject> projects, String mainClass) throws E
tool.setClassLoader(classLoader);
tool.setOutputDir(outputDir);
tool.setSources(sources);
tool.setCopyOpenApiSpecTo(
copyOpenApiSpecTo == null ? null : copyOpenApiSpecTo.stream().map(File::toPath).toList());
trim(includes).ifPresent(tool::setIncludes);
trim(excludes).ifPresent(tool::setExcludes);
if (javadoc != null && !javadoc.trim().isEmpty()) {
Expand All @@ -92,48 +88,10 @@ protected void doExecute(List<MavenProject> projects, String mainClass) throws E
var result = tool.generate(mainClass);

var adocPath = ofNullable(adoc).orElse(List.of()).stream().map(File::toPath).toList();
var written = new ArrayList<Path>();
for (var format : OpenAPIGenerator.Format.values()) {
written.addAll(tool.export(result, format, Map.of("adoc", adocPath)));
tool.export(result, format, Map.of("adoc", adocPath))
.forEach(output -> getLog().info(" writing: " + output));
}
written.forEach(output -> getLog().info(" writing: " + output));

if (copyOpenApiSpecTo != null) {
var destination = copyOpenApiSpecTo.toPath();
copySpec(written, destination);
getLog().info(" copying: " + destination);
}
}

public static void copySpec(List<Path> written, Path destination) throws IOException {
var format = specFormat(destination);
var source =
written.stream()
.filter(path -> path.getFileName().toString().endsWith("." + format.extension()))
.findFirst()
.orElseThrow(
() ->
new IOException(
String.format(
"OpenAPI %s output not found for copyOpenApiSpecTo: %s",
format.name(), destination)));
var parent = destination.getParent();
if (parent != null) {
Files.createDirectories(parent);
}
Files.copy(source, destination, StandardCopyOption.REPLACE_EXISTING);
}

public static OpenAPIGenerator.Format specFormat(Path destination) {
var name = destination.getFileName().toString().toLowerCase(Locale.ROOT);
if (name.endsWith(".json")) {
return OpenAPIGenerator.Format.JSON;
}
if (name.endsWith(".yaml") || name.endsWith(".yml")) {
return OpenAPIGenerator.Format.YAML;
}
throw new IllegalArgumentException(
"copyOpenApiSpecTo must end with .yaml, .yml or .json: " + destination);
}

private Optional<String> trim(String value) {
Expand Down Expand Up @@ -239,7 +197,7 @@ public String getJavadoc() {
*
* @return Destination file.
*/
public @Nullable File getCopyOpenApiSpecTo() {
public @Nullable List<File> getCopyOpenApiSpecTo() {
return copyOpenApiSpecTo;
}

Expand All @@ -255,7 +213,7 @@ public String getJavadoc() {
*
* @param copyOpenApiSpecTo Destination file.
*/
public void setCopyOpenApiSpecTo(@Nullable File copyOpenApiSpecTo) {
public void setCopyOpenApiSpecTo(@Nullable List<File> copyOpenApiSpecTo) {
this.copyOpenApiSpecTo = copyOpenApiSpecTo;
}
}
57 changes: 0 additions & 57 deletions modules/jooby-maven-plugin/src/test/java/io/jooby/maven/OpenAPIMojoTest.java
View file
Open in desktop

This file was deleted.

Loading
Loading