Documentación de APIs con Django REST, Swagger y OpenAPI

When we create an API, the main objective is that other systems or developers can integrate with our system in an efficient way. To achieve this, a clear and updated documentation is essential. Tools such as DRF Spectacular and Swagger make this task easier, automating the generation of documentation and allowing it to be always synchronized with our code.

How to document an API automatically?

• Django and Django REST Framework (DRF) offer us the possibility of using a library called DRF Spectacular. This tool follows the OpenAPI standard to generate automatic documentation.
• This standard allows any change in the views or API endpoints to be immediately reflected in the documentation, without the need to modify it manually.

What is Swagger and how to use it for your API documentation?

• Swagger is a visual interface that displays the documentation generated by DRF Spectacular. It allows developers to interact directly with the API, test endpoints and review possible parameters and responses.
• In addition, it offers the option to download an OpenAPI schema file that can be used by other tools or interfaces.

How to create the documentation application in Django?

1. Create a new application called docs from the terminal.
   • Register this application in the Installed Apps list in the settings.py file.
2. Install the DRF Spectacular library by executing the command pip install drf-spectacular.
   • Also register this library in the installed applications.
3. Configure an automatic scheme in settings.py making sure there are no duplicates in the configuration.

How to add Swagger and Redoc URLs?

• Inside the urls.py file of the docs application, add the URLs corresponding to Swagger and Redoc.
• Don't forget to import correctly the paths with path from django.urls.
• Add the URLs of the docs application to the main URL file of the project so that they are accessible.

What is the difference between Swagger and Redoc?

• Swagger provides an interface where you can interact with the endpoints and test the responses without leaving the browser.
• Redoc is another interface that allows you to navigate between endpoints in a more organized way, with a search engine and a list of available resources. It also shows details of possible responses and errors.

How to improve the documentation of each endpoint?

• You can add descriptions to each of the endpoints in your view classes, using Python comments.
• These comments will automatically appear in the Swagger or Redoc documentation, making it easier for other developers to understand the behavior of each resource.

What are the advantages of the OpenAPI standard?

• OpenAPI allows any tool that follows this standard, such as Swagger or Redoc, to interpret the API schema and generate visual documentation.
• It is a widely used format and compatible with different user interfaces.

How to update the documentation when modifying the code?

• The main advantage of using DRF Spectacular is that when the code is modified, the documentation is automatically updated. This ensures that it is always synchronized and prevents you from having to edit the documentation manually.