How to auto-generate OpenAPI docs for Django, Flask, Spring and Rails apps
Tags: python, java, rails, webdev
Published: 2021-11-18 18:29:20

The [OpenAPI Specification](https://en.wikipedia.org/wiki/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](https://appland.com/docs/reference/cli-client.html) 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.
1. When you run your tests, the AppMap agent records [AppMaps](https://appland.com/products/appmap), which are visual, interactive maps of your application’s code. AppMaps include details about all of the web service requests made in your tests.
1. 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](https://appland.com/docs/quickstart/).

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](https://github.com/applandinc/appmap-agent-js) right now, so if you’re interested in trying that out let us know [in our Discord](https://discord.com/invite/N9VUap6).

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`](https://swagger.io), generated and imported in minutes.

## How to auto-generate OpenAPI documentation for Java Spring applications

 {% youtube kPsTWA1AxmM %}

- `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](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:
    ```xml
    <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`](https://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](https://dev.to/appland/how-to-auto-generate-swagger-openapi-doc-for-your-web-services-3npn).