Using the open source e-commerce framework Django-Oscar as an example.
API documents are usually a developer’s first introduction to a project; however, they can be out of date or incorrect because developers on the project have to go in and update the documents manually each time the code changes. This is not only a waste of developers’ time, but it is easy to forget to do it altogether. The industry says "API first" - starting with an API Document - is the way to build applications, but this approach can be overlooked when there are tight deadlines.
AppMap is a free, dynamic runtime analysis tool that makes it easy to automatically generate API documents. Automatic OpenAPI generation can also be incorporated into your CI/CD system to prevent the documents from ever being out of date or incorrect. The days of manual API documentation writing are over. Write your code, run your code, and the document will appear in your repository.
Add AppMap to Django-Oscar
In Part One of this series, you learned how to generate AppMaps for the open-source project Django-Oscar. AppMaps are visual representations of code that allow developers to dig into the trace of their HTTP requests, function calls, and database writes. To install AppMap libraries into the Django-Oscar codebase, add the AppMap PyCharm extension.
If you are not using VS Code or Jetbrains, or if you want to incorporate OpenAPI generation into your CI/CD system, you can install the AppMap CLI and generate OpenAPI docs on the command line.
Run the Django-Oscar Test Suite
Set your environment variable as shown below, and run the PyTest command to execute the Django-Oscar test suite. The test coverage is extensive and will take a while to run, so feel free to run a subset of the tests first just to see how the API generation works. You can learn more about generating AppMaps from tests in Python in the AppMap Documentation.
APPMAP_LOG_LEVEL=info pytest -svv
After running the full test suite, you’ll have a collection of code-accurate AppMaps with all the up to date API request information within.
Click on one of the AppMaps in the sidebar to expand it and explore the dependencies within the project.
Generate the OpenAPI Spec
Now that our API requests have been recorded within our AppMaps, you can generate the OpenAPI v3 supported specification file via either PyCharm or using the AppMap CLI. From there you can import the file into Postman, other API management tools, or share with your team.
After the Django-Oscar test cases complete, click the “Generate OpenAPI” button.
This will open the OpenAPI generator. Then click the “Generate OpenAPI Documents” button and your OpenAPI specification will be displayed in the editor. Save this data anywhere you need it for later usage or distribution.
For example: I loaded this API Specification into Postman as a new collection.
Generate OpenAPI Document with AppMap CLI
If you are not a PyCharm user, or if you want to incorporate OpenAPI generation as part of your CI process, you can run the AppMap CLI command after the tests have completed to similarly output the API documents to a user-defined output file.
The AppMap CLI is written in JavaScript, which makes it easy to run across a variety of platforms. To install the AppMap CLI, you need Node.js installed, or you can grab pre-built binaries for @appland/appmap on Github. To install AppMap CLI after Node.js is installed, run the following command.
npx @appland/appmap@latest openapi --output-file openapi.yml
Import the OpenAPI documents into other tools to more easily interact with your APIs, test new or updated features, and finally export the OpenAPI documents to your users so that they will know how to interact with your application as well.
Now that you've generated the API document locally, add this command to your CI system to update your OpenAPI docs as your code changes.
You can learn more about other features of AppMap by reviewing our documentation or you can join the developers in our community Slack.
Top comments (0)