Swagger or the OpenAPI Specification is a wonderful thing, because it lets you:
- See your whole web services catalog and actively interact with all of the API functions
- Debug your webservices in a very granular way
- Observe your web services test coverage visually
- Diff the web services changes by committing your Swagger YAML and comparing across versions using standard source diff
The trouble is, writing Swagger files – and keeping them accurate and up-to-date – is a real challenge.
But when API documentation isn’t kept accurate or up-to-date, devs face frustrating collaboration set-backs, broken applications and integrations, and an overall inefficient use of OpenAPI automation tools.
So, here’s an easy, free solution: Use AppMap to automatically generate Swagger 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 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 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
openapitool generates OpenAPI documentation from the recorded AppMaps.
You can execute this flow in your local environment or in automated CI/CD pipelines. And you can download AppMap with OpenAPI generation for free for your Django and Flask apps here.
Here’s a video walk-through of how to set up and use AppMap Swagger/OpenAPI generation for Python (we’ve included a script summary below in case you prefer to read vs. watch). Thanks for reading and watching!
How to auto-generate OpenAPI documentation for Python Django and Flask applications
00:00Today I am going to demonstrate how to automatically generate OpenAPI docs for my Python application with AppMap.
00:10My 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:25Installing 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 @appland/appmap install
The installer asks me to confirm the environment and sets up AppMap automatically.
00:46Now I am ready to record AppMaps. I’ll simply run tests with
set APPMAP=trueon Windows) in the environment:
if I used Windows, it would be:
set APPMAP=true pytest
00:55When the tests finish, AppMap files will be stored in the
tmp/appmap/pytestsubfolder of my project.
01:05In 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:11And that’s it! The
misago-openapi.ymlis 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:35I can inspect
misago-openapi.ymlin my IDE or in any OpenAPI tool. Let me upload it to
01:48And here it is, an OpenAPI documentation of the Misago app in swagger.io, generated and imported in minutes.