Python server programming: API documentation using django-rest-swagger

With the development of the Internet, Web applications and APIs are becoming more and more common. Python is a popular programming language that can be used to build web applications and APIs. In Python, Django is a powerful web framework that provides many useful features, including models, views, and templates that simplify web development. On the other hand, API documentation is an important task that helps developers understand the functionality and usage of the API. In this article, we will introduce how to use django-rest-swagger to document the API.

1. Install django-rest-swagger

First, you need to install django-rest-swagger. You can use pip to install:

pip install django-rest-swagger

2. Integrate django-rest-swagger

Add the following content to Django’s settings.py file:

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'rest_framework_swagger',
]

MIDDLEWARE = [
    # ...
    'corsheaders.middleware.CorsMiddleware',
    'django.middleware.common.CommonMiddleware',
]

SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': False, #关闭session认证
    'APIS_SORTER': 'alpha',
    'JSON_EDITOR': True
}

Then, add the following content to Django's urls.py file:

from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='API Document')
urlpatterns = [
    # ...
    url(r'^docs/', schema_view),
]

After completing the above configuration, visit http://localhost:8000/docs/ to see the API documentation page.

3. Configuring swagger

Modify Django’s settings.py file and add the following content:

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

This will make the API return document data in coreapi format, This enables rendering in Swagger UI.

4. Generate API documentation

Now you can start writing API views. Add some necessary metadata to the view, which will be used to generate API documentation. For example:

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import authentication, permissions

class HelloWorld(APIView):
    """
    简要描述API的功能
    """
    authentication_classes = [authentication.TokenAuthentication]
    permission_classes = [permissions.IsAuthenticated]

    def get(self, request, format=None):
        """
        获取数据

        所需参数：
        * param1 - 参数1说明
        * param2 - 参数2说明

        返回数据：
        * status - response的状态
        """
        content = {'message': 'Hello, World!'}
        return Response(content)

In this view, some metadata is added, such as a brief description, parameter description, and return description. These metadata will be used by django-rest-swagger to generate API documentation.

5. View API documentation

Now, you can visit http://localhost:8000/docs/ to view the API documentation. In the documentation page, you will see a list of all API views, each with its own methods, parameters, and return instructions. You can also test the API on the page to check if it is working properly.

Summary

Using django-rest-swagger can easily document the API so that developers can understand the usage and functions of the API. In this article, we introduce how to integrate django-rest-swagger in Django and generate API documentation. I hope this article can help readers better understand Python server programming and API documentation technology.

The above is the detailed content of Python server programming: API documentation using django-rest-swagger. For more information, please follow other related articles on the PHP Chinese website!