📦 Generate the OpenAPI description of your Spring Boot application at build time, with Maven

📖 Documentation · 🚀 Getting started · ⚙️ Configuration · 📊 Site report · 🍃 springdoc-openapi

💖 Sponsored by

               

_{If you ❤️ springdoc-openapi, become a sponsor: it covers the project expenses and helps it grow.}

---

springdoc-openapi-maven-plugin writes the OpenAPI description of your application to a file during the build, so you can commit it, diff it, publish it with your artifacts, or feed it to code generators. ✨

It works together with the spring-boot-maven-plugin: the application is started before the integration tests, the plugin downloads the description that springdoc-openapi serves at /v3/api-docs, and the application is stopped again. Because the description comes from the running application, it is exactly what springdoc-openapi serves at runtime.

🚀 Getting started

Add both plugins to the <build><plugins> section of your pom.xml:

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <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>1.6</version>
  <executions>
    <execution>
      <id>integration-test</id>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Then run:

mvn verify

👉 The description is written to target/openapi.json.

🧭 Compatibility

The plugin only calls an HTTP endpoint, so it works with any application that serves an OpenAPI description:

Spring Boot	springdoc-openapi
🍃 4.x	3.x
🍃 3.x	2.x
🍂 2.x and 1.x	1.x

The plugin runs on Java 8 and later, with Maven 3.6.3 and later.

🎯 Goals

Goal	Default phase	Description
springdoc-openapi:generate	integration-test	Downloads the OpenAPI description from the running application and writes it to a file
springdoc-openapi:report	site	Adds a Swagger UI page to the Maven site, see Site report (since 1.6)

⚙️ Configuration

Each parameter of the generate goal can also be set from the command line with its user property, for example mvn verify -Dspringdoc.skip=true.

Parameter	User property	Default	Description
apiDocsUrl	springdoc.apiDocsUrl	http://localhost:8080/v3/api-docs	URL of the OpenAPI description (JSON or YAML)
outputFileName	springdoc.outputFileName	openapi.json	Name of the generated file
outputDir	springdoc.outputDir	${project.build.directory}	Directory of the generated file
attachArtifact	springdoc.attachArtifact	false	Attach the file to the project, so it is installed and deployed with the other artifacts (classifier openapi)
attachArtifactClassifier	springdoc.attachArtifactClassifier	openapi	Classifier of the attached file
headers		none	HTTP headers sent with the request, for example for authentication
timeout	springdoc.timeout	60	Connect and read timeout of the request, in seconds (0 for none)
skip	springdoc.skip	false	Skip the execution
failOnError	springdoc.failOnError	false	Fail the build if the description cannot be downloaded or written

<plugin>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-maven-plugin</artifactId>
  <version>1.6</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>${project.build.directory}/openapi</outputDir>
    <attachArtifact>true</attachArtifact>
    <failOnError>true</failOnError>
    <headers>
      <Authorization>Bearer my-token</Authorization>
    </headers>
  </configuration>
</plugin>

Tip

Set failOnError to true on CI. By default, a failure is only logged, and the build goes on without the file.

When the build fails, Maven skips spring-boot:stop, so the application keeps running. Stop it before the next build, or it answers the next build's requests instead of the new application.

💡 Recipes

• 📄 YAML: point apiDocsUrl to http://localhost:8080/v3/api-docs.yaml and set outputFileName to openapi.yaml.

• 🗂️ Groups: add one <execution> per group, each with its own apiDocsUrl (for example http://localhost:8080/v3/api-docs/admin) and outputFileName, and its own attachArtifactClassifier if the files are attached.

• ✨ Pretty-printed JSON: the file is saved exactly as served, so enable springdoc.writer-with-default-pretty-printer=true in the application, for example in the spring-boot-maven-plugin configuration:

  <arguments>
    <argument>--springdoc.writer-with-default-pretty-printer=true</argument>
  </arguments>

• 🔌 Another port: change the port of the application and apiDocsUrl together, for example -Dspring-boot.run.arguments=--server.port=9090 -Dspringdoc.apiDocsUrl=http://localhost:9090/v3/api-docs.

📊 Site report

Note

The report goal is available since version 1.6.

The report goal adds an OpenAPI Documentation page, rendered with Swagger UI, under Project Reports in the Maven site. It reads the file written by the generate goal (by default target/openapi.json), and if that file does not exist, it fetches the description from apiDocsUrl.

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>1.6</version>
      <reportSets>
        <reportSet>
          <reports>
            <report>report</report>
          </reports>
        </reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>

Then generate the description and the site in the same build:

mvn verify site

👉 The page is written to target/site/springdoc-openapi/index.html.

Parameter	User property	Default	Description
apiDocsFile	springdoc.apiDocsFile	${project.build.directory}/openapi.json	File written by the generate goal
apiDocsUrl	springdoc.apiDocsUrl	http://localhost:8080/v3/api-docs	URL used when apiDocsFile does not exist
headers		none	HTTP headers sent with the request to apiDocsUrl
timeout	springdoc.timeout	60	Connect and read timeout of the request to apiDocsUrl, in seconds
siteReportName	springdoc.report.name	OpenAPI Documentation	Name in the Project Reports menu
siteReportDescription	springdoc.report.description	OpenAPI specification rendered with Swagger UI	Description in the Project Reports page
siteReportDirectory	springdoc.report.directory	springdoc-openapi	Directory of the page in the site
swaggerUiVersion	springdoc.swaggerUiVersion	5.34.1	Swagger UI version, loaded from unpkg.com
skip	springdoc.report.skip	false	Skip the report

Important

The report needs maven-site-plugin 3.9.1 or later. Maven 3.9 uses 3.12.1 by default; with an older Maven, set the version of maven-site-plugin in your pom.xml.

The report only supports a JSON description (/v3/api-docs), not YAML. The Swagger UI files are loaded from unpkg.com, so the page needs internet access when it is viewed.

💬 Getting help

• 📖 Read the plugin documentation and the springdoc-openapi documentation
• 🙋 Ask questions on Stack Overflow with the springdoc tag
• 🐛 Report bugs in GitHub issues, with a minimal reproducer

Note

springdoc-openapi is a community project, not maintained by the Spring team.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.adoc and the Code of Conduct.

To build the plugin and install it in your local Maven repository:

./mvnw install

Thanks to all our contributors 🙏

Special thanks to JetBrains for their support.

📄 License

springdoc-openapi-maven-plugin is Open Source software released under the Apache 2.0 license.