26
loading...
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:
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!
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:
npm install @appland/appmap
npx appmap 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 appmap 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.
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 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:
npm install @appland/appmap
npx 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 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.
26