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:
- 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 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.
- 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 withAPPMAP=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 thetmp/appmap/pytest
subfolder of my project.-
01:05
In the final step, I will run the AppMapopenapi
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! Themisago-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 inspectmisago-openapi.yml
in my IDE or in any OpenAPI tool. Let me upload it toswagger.io
now.01:48
And here it is, an OpenAPI documentation of the Misago app inswagger.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 usesMaven
and the AppMap installer adds the AppMap Maven plugin to the masterpom.xml
file. A similar gradle plugin exists for gradle-built applications.-
01:01
Let me quickly review thepom.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 orjacoco
. 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 AppMapopenapi
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 inspectwebgoat-openapi.yml
in my IDE or in any OpenAPI tool. Let me upload it toswagger.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.
Top comments (0)