Django-Oasis¶

Django-Oasis (后面简称 Oasis) 旨在更加高效地编写 HTTP API。

使用前提¶

[必要] 该项目基于 Django 框架，所有在使用前需要对 Django 有基本的开发能力。
[可选] 项目还使用了 OpenAPI 规范 (OAS) 来描述接口。它可以创建交互式接口文档，实现测试用例自动化，还能用于生成客户端代码等等。但不了解 OAS 也并不影响使用。

简单的示例¶

这里定义了一个 Book 模型:

models.py [示例1]¶

from django.db import models


class Book(models.Model):
    title = models.CharField("书名", max_length=20)
    created_at = models.DateTimeField("创建时间", auto_now_add=True)

并使用 Oasis 编写两个接口，为其实现 “查” 和 “增” 的功能:

views.py [示例1]¶

from django_oasis.common import model2schema
from django_oasis.core import Operation, Resource
from django_oasis.pagination import PagePagination
from django_oasis.parameter import JsonData

from .models import Book


# Oasis 并不能直接理解 Django Model 中的定义，
# 所以需要使用 `model2schema` 将 Book 模型转换成 Schema。
class BookSchema(model2schema(Book)):
    pass


@Resource("/books")
class BookListAPI:
    # get 方法负责处理 GET 请求，用于查询 Book
    def get(self, pagination=PagePagination(BookSchema)):
        # 这里使用了 Oasis 提供的分页功能
        return pagination.paginate(Book.objects.all())

    # post 方法负责处理 POST 请求，用于新增 Book
    @Operation(response_schema=BookSchema)
    def post(self, data=JsonData(BookSchema)):
        return Book.objects.create(**data)

这些请求接口会被 Oasis 处理并转换为 Django 的视图函数和路由，这使其能够成为 Django 项目的一部分。并且还为接口生成了 OAS，将 OAS 导入文档生成工具 (如 SwaggerUI)，便可对外展示接口文档了。

这是由上面示例生成的 Swagger 文档：

SwaggerUI [示例1]

功能说明¶

Oasis 使用自有的规则来编写接口代码，而不是使用 Django 的视图函数。
Oasis 并不是生成文档，而是生成 OAS，OAS 可以用来做 API 文档和自动化测试使用。而且在整个开发过程中，几乎不需要手写 OAS。
Oasis 内置了一个简单配置的 swagger-ui，仅需几行代码即可查看接口文档。而且 Oasis 是以 HTTP 接口的形式暴露 OAS 数据，所以也可以选择喜欢的 API 可视化工具，或者自动化测试工具。
Schema 是 Oasis 实现的核心，它负责定义数据结构，验证数据，并提供序列化及反序列化功能。

目录¶

示例

RESTful