How to auto-generate OpenAPI docs for Django, Flask, Spring and Rails apps

The OpenAPI Specification (also/previously called Swagger) helps developers model, document, implement and test web applications and services APIs. It’s a wonderful thing! And unsurprisingly, it’s embraced by dev teams and documentation communities across the globe.

The trouble is, keeping OpenAPI documentation accurate and in sync with implementation updates -- particularly for fast-evolving applications and services -- can be really challenging and time consuming. It’s also a never-ending task.

Because the OpenAPI standard can be such an intimidating format to work with (it takes a true yaml guru to manage long configuration files quickly and precisely!), API documentation is often inaccurate and outdated. And when API documentation isn’t accurate or up-to-date, devs face frustrating collaboration set-backs, broken applications and integrations, and an overall inefficient use of OpenAPI automation tools.

To help devs avoid the risks associated with inaccurate and outdated API documentation, we built a free and open source tool called AppMap that automatically generates OpenAPI documentation from running code. AppMap ensures your API documentation is always current, accurate and readily available -- no tedious, manual labor required. Huzzah!

Here’s how AppMap OpenAPI generation works:

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

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 preferred framework here.

Below is a script summary for the AppMap OpenAPI generation for Python video, in case you prefer to read vs. watch. If you’re working in Java or Ruby, I’ve included videos for those below, too. We’re putting the finishing touches on AppMap for JavaScript right now, so if you’re interested in trying that out let us know in our Discord.

Thanks for reading and watching!

How to auto-generate OpenAPI documentation for Python Django and Flask applications

• 00:00 Today I am going to demonstrate how to automatically generate OpenAPI docs for my Python application with AppMap.

• 00:10 My application is Misago - a popular forum application written in Python, Django, ES6 and React.js. I already have a Python development environment set up and I am ready to install AppMap and run tests.

• 00:25 Installing AppMap is easy with the command line installation tool (it requires Node.js). Here's a terminal window with the Misago dev environment active. In the project folder, I'll run:
  

  npx @appland/appmap@latest install
  

  The installer asks me to confirm the environment and sets up AppMap automatically.

• 00:46 Now I am ready to record AppMaps. I'll simply run tests with APPMAP=true in the environment:
  

  APPMAP=true pytest
  

  if I used Windows, it would be:
  

  set APPMAP=true
  pytest
  

• 00:55 When the tests finish, AppMap files will be stored in the tmp/appmap/pytest subfolder of my project.

• 01:05 In the final step, I will run the AppMap openapi command:
  

  npx @appland/appmap@latest openapi --openapi-title "Misago" --openapi-version "0.27.0" -o misago-openapi.yaml --appmap-dir=tmp/appmap/pytest
  

• 01:11 And that's it! The misago-openapi.yml is my generated OpenAPI documentation for my application. If my application consisted of additional microservices, I would generate documentation for each service using the same approach: 1) install AppMap agent, 2) run tests, 3) generate documentation.

• 01:35 I can inspect misago-openapi.yml in my IDE or in any OpenAPI tool. Let me upload it to swagger.io now.

• 01:48 And here it is, an OpenAPI documentation of the Misago app in swagger.io, generated and imported in minutes.

How to auto-generate OpenAPI documentation for Java Spring applications

• 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@latest 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 AppMaps:
  

  ./mvnw test
  

  If I used Windows:
  

  mvnw test
  

  When the tests finish, AppMap files will be stored in the target/appmap subfolders of all sub-modules that have tests.

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

  npx @appland/appmap@latest 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 AppMaps.

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

How to auto-generate OpenAPI documentation for Ruby on Rails applications

Please visit How to auto-generate detailed Swagger/OpenAPI for all your Rails routes.