📦 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.