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

Posted 21 Dec 2021 by Lizzie & Petr

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 openapi tool 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: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 @appland/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 (set APPMAP=true on Windows) 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.