Skip to content

Add site plugin for this project #80

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
patpatpat123 wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add site plugin for this project #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
613f27b
Update pom.xml
patpatpat123 Apr 3, 2026
bf1a094
Update README.md
patpatpat123 Apr 3, 2026
17349c3
Create SpringDocOpenApiReportMojo.java
patpatpat123 Apr 3, 2026
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
190 changes: 128 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
## **Introduction to springdoc-openapi-maven-plugin**

The aim of springdoc-openapi-maven-plugin is to generate json and yaml OpenAPI description during runtime. If you want to get swagger definitions properly, the application should completely running as locally.
The plugin works during integration-tests phase, and generate the OpenAPI description.
The plugin works in conjunction with spring-boot-maven plugin.
The plugin works during integration-tests phase, and generate the OpenAPI description.
The plugin works in conjunction with spring-boot-maven plugin.

You can test it during the integration tests phase using the maven command:

Expand All @@ -16,54 +16,54 @@ In order to use this functionality, you need to add the plugin declaration on th

```xml
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>${spring-boot-maven-plugin.version}</version>
<configuration>
<jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
</configuration>
<executions>
<execution>
<id>pre-integration-test</id>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>last-release-version</version>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>${spring-boot-maven-plugin.version}</version>
<configuration>
<jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
</configuration>
<executions>
<execution>
<id>pre-integration-test</id>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>last-release-version</version>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
```

## **Custom settings of the springdoc-openapi-maven-plugin**

It possible to customise the following plugin properties:
* attachArtifact: install / deploy the api doc to the repository
* The default value is: false
* apiDocsUrl: The local url of your (json or yaml).
* apiDocsUrl: The local url of your (json or yaml).
* The default value is: http://localhost:8080/v3/api-docs
* outputDir: The output directory, where to generate the OpenAPI description. The directory name shouldn't start with "/".
* The default value is: ${project.build.directory}
* outputFileName: The file name that contains the OpenAPI description.
* outputFileName: The file name that contains the OpenAPI description.
* The default value is: openapi.json
* skip: Skip execution if set to true.
* The default value is: false
Expand All @@ -74,31 +74,97 @@ It possible to customise the following plugin properties:

```xml
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>last-release-version</version>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
<outputFileName>openapi.json</outputFileName>
<outputDir>home/springdoc/maven-output</outputDir>
<skip>false</skip>
<failOnError>true</failOnError>
<headers>
<header1key>header1value</header1key>
<header2key>header2value</header2key>
</headers>
</configuration>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>last-release-version</version>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
<outputFileName>openapi.json</outputFileName>
<outputDir>home/springdoc/maven-output</outputDir>
<skip>false</skip>
<failOnError>true</failOnError>
<headers>
<header1key>header1value</header1key>
<header2key>header2value</header2key>
</headers>
</configuration>
</plugin>
```

## **Site Report: Swagger UI in Maven Project Reports**

The plugin provides a `report` goal that generates a static Swagger UI page and places it in the Maven site under **Project Reports**.

The report reads the OpenAPI spec from the file produced by the `generate` goal (default `target/openapi.json`). If the file does not exist, it falls back to fetching from `apiDocsUrl`.

**Recommended workflow:** run `mvn verify` first (to generate the spec), then `mvn site`.

Add the plugin to the `<reporting>` section of your POM:

```xml
<reporting>
<plugins>
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>last-release-version</version>
<reportSets>
<reportSet>
<reports>
<report>report</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
```

### Report configuration properties

| Property | Default | Description |
|---|---|---|
| `springdoc.report.skip` | `false` | Skip report generation |
| `springdoc.apiDocsFile` | `${project.build.directory}/openapi.json` | Path to a pre-generated OpenAPI spec file |
| `springdoc.apiDocsUrl` | `http://localhost:8080/v3/api-docs` | Fallback URL when spec file is absent |
| `springdoc.report.name` | `OpenAPI Documentation` | Name in Project Reports navigation |
| `springdoc.report.description` | `OpenAPI specification rendered with Swagger UI` | Description in Project Reports |
| `springdoc.report.directory` | `springdoc-openapi` | Subdirectory under the site output |
| `springdoc.swaggerUiVersion` | `5` | Swagger UI version for CDN (unpkg.com) |

### Example with custom configuration

```xml
<reporting>
<plugins>
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>last-release-version</version>
<configuration>
<siteReportName>API Reference</siteReportName>
<swaggerUiVersion>5.18.2</swaggerUiVersion>
</configuration>
<reportSets>
<reportSet>
<reports>
<report>report</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
```

# **Thank you for the support**

* Thanks a lot [JetBrains](https://www.jetbrains.com/?from=springdoc-openapi) for supporting springdoc-openapi project.
Expand Down
16 changes: 16 additions & 0 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,22 @@
<version>3.6.4</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-artifact</artifactId>
<version>3.8.4</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.maven.reporting</groupId>
<artifactId>maven-reporting-api</artifactId>
<version>3.1.0</version>
</dependency>
<dependency>
<groupId>org.apache.maven.reporting</groupId>
<artifactId>maven-reporting-impl</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies>

<build>
Expand Down
Loading