Tổng Quan
Trong các công ty, nhóm phát triển frontend và backend thường tách biệt. Nhóm backend cần viết tài liệu API để cung cấp cho nhóm frontend sử dụng.
Mẫu tài liệu tham khảo: https://open.weibo.com/wiki/2/comments/show
Cách Viết Tài Liệu API
Phương pháp 1: Sử dụng Word hoặc Markdown - viết thủ công - nhiều công ty áp dụng cách này.
Phương pháp 2: Sử dụng nền tảng bên thứ ba - viết bán tự động - một số công ty sử dụng.
Tham khảo thêm: https://blog.csdn.net/weixin_44337261/article/details/121005675
Phương pháp 3: Công ty tự xây dựng nền tảng API - dữ liệu lưu trữ nội bộ.
Tham khảo thêm: https://zhuanlan.zhihu.com/p/366025001
Phương pháp 4: Tự động hóa tạo tài liệu API - ít phổ biến hơn - tự động sinh ra và xuất ra - nhập vào YAPI, có thể dùng CoreAPI, Swagger.
Sử Dụng CoreAPI
1. Cài Đặt Phụ Thuộc
pip install coreapi
2. Thiết Lập Đường Dẫn Truy Cập Tài Liệu API
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
path('tai-lieu/', include_docs_urls(title='Tiêu Đề Trang'))
]
3. Định Nghĩa Vị Trí Mô Tả Tài Liệu
Đối với lớp xem đơn lẻ, có thể sử dụng chuỗi tài liệu của lớp xem như sau:
class SachListView(generics.ListAPIView):
"""
Trả về tất cả thông tin sách.
"""
Đối với lớp xem chứa nhiều phương thức, định nghĩa từng phương thức trong chuỗi tài liệu của lớp xem:
class SachListCreateView(generics.ListCreateAPIView):
"""
get:
Trả về tất cả thông tin sách.
post:
Tạo mới sách.
"""
Đối với ViewSet, vẫn định nghĩa trong chuỗi tài liệu của lớp xem nhưng phân biệt bằng tên hành động:
class ThongTinSachViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
"""
list:
Trả về danh sách sách.
retrieve:
Trả về chi tiết sách.
latest:
Trả về sách mới nhất.
read:
Sửa đổi lượng đọc sách.
"""
4. Truy Cập Trang Tài Liệu API
Truy cập qua trình duyệt tại địa chỉ 127.0.0.1:8000/tai-lieu/, sẽ thấy tài liệu API tự động tạo.
Nếu Gặp Lỗi
# AttributeError: 'AutoSchema' object has no attribute 'get_link'
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
# Phiên bản mới DRF schema_class mặc định là rest_framework.schemas.openapi.AutoSchema
}
Lưu Ý
-
Trong ViewSet, tên retrieve được gọi là read trên trang tài liệu API.
-
Mô tả tham số cần được định nghĩa trong lớp mô hình hoặc lớp serialize với tùy chọn help_text, ví dụ:
class HocSinh(models.Model):
...
tuoi = models.IntegerField(default=0, verbose_name='Tuổi', help_text='Tuổi')
...
Hoặc
class HocSinhSerializer(serializers.ModelSerializer):
class Meta:
model = HocSinh
fields = "__all__"
extra_kwargs = {
'tuoi': {
'required': True,
'help_text': 'Tuổi'
}
}