How to auto-generate OpenAPI docs for Spring apps

Posted 22 Dec 2021 by Lizzie and Petr

Recently, we shared why we 💜 Swagger and how you can auto-generate it for your Django and Flask apps. Today, we’re going to share how you can auto-generate Swagger (or OpenAPI docs) for your Java Spring apps!

Here’s the deal: AppMap is a free and open source tool that you can use to automatically generate Swagger from running code. AppMap ensures your API documentation is always accurate and up-to-date – no tedious, time-consuming, manual labor required. YAY.

Here’s how AppMap Swagger generation works:

An AppMap agent is added to the tool chain of your application as a new build dependency.
When you run your tests, the AppMap agent records AppMap Data, which are visual, interactive maps of your application’s code. AppMap Diagrams include details about all of the web service requests made in your tests.
The AppMap openapi tool generates OpenAPI documentation from the recorded AppMap Data.

You can execute this flow in either your local environment or in automated CI/CD pipelines. And you can download AppMap with OpenAPI generation for free for your Spring apps here.

Here’s a video walk-through of how to set up and use AppMap Swagger/OpenAPI generation for Java (we’ve included a script summary below in case you prefer to read vs. watch). Thanks for reading and watching!

00:00 I am going to demonstrate how to automatically generate OpenAPI docs for my Java Spring application with AppMap.
00:10 My application is WebGoat - a deliberately insecure application that lets developers test vulnerabilities commonly found in Java-based applications that use common and popular open source components.

You can find the WebGoat repository used in this demo here: https://github.com/land-of-apps/WebGoat.git
00:24 I already have a Java environment set up and am ready to install AppMap and run tests.
00:30 Installing AppMap is easy with the command line installation tool (which requires Node.js). In the WebGoat project folder I’ll run this:
```
  npx @appland/appmap install
```
The installer asks me to confirm the environment and sets up AppMap for the project automatically.
00:48 WebGoat uses Maven and the AppMap installer adds the AppMap Maven plugin to the master pom.xml file. A similar gradle plugin exists for gradle-built applications.
01:01 Let me quickly review the pom.xml files of the project, because it’s always recommended to verify the build configuration of complex Java applications.

The standard surefire plugin configuration was modified and the change unfortunately breaks all Java agent plugins such as AppMap or jacoco. To quickly fix this issue, I’ve modified the surefire configuration:
```
  <configuration>
      <forkCount>1</forkCount>
      <reuseForks>true</reuseForks>
      <argLine>
          @{argLine} --illegal-access=permit
      </argLine>
  </configuration>
```
01:15 Now I will run tests to record AppMap Data:
```
  ./mvnw test
```
If I used Windows:
```
  mvnw test
```
When the tests finish, AppMap files will be stored in the tmp/appmap subfolders of all sub-modules that have tests.

01:32 In the final step, I will install and run the AppMap openapi command:

  npm install @appland/appmap
  npx @appland/appmap openapi --openapi-title "WebGoat" --openapi-version "8.2.0" -o webgoat-openapi.yaml --appmap-dir=.

01:39 And that’s it! webgoat-openapi.yml is my generated OpenAPI documentation. If my application consisted of additional microservices, I would generate documentation from each service using the same approach: 1) install the AppMap agent, 2) run tests, 3) generate OpenAPI documentation from AppMap Data.
02:05 I can inspect webgoat-openapi.yml in my IDE or in any OpenAPI tool. Let me upload it to swagger.io now.
02:11 And here it is, the OpenAPI documentation of the WebGoat app generated and imported to swagger.io in minutes.