djangorestframework开发出属于你自己的接口文档

Posted 2022-04-21 qyk1995

经过两个星期的研究，终于做出来了。之前看了很多博客都是创建数据库去增加参数，但不是我想要的。因此就没有使用数据库去增加参数。

背景介绍：因为公司java人员开发出来一个自己的swagger界面，因为领导就说python是不是应该也可以开发出swagger界面呢？因此就把此任务交给刚入职3个月的员工、

一、环境搭建：

软件版本自己也试了好多版，终于弄了一个适合公司的版本。本次python版本是2.7.12。下面可能是你需要安装的软件包。请按顺序安装即可。

pytz==2019.1
django==1.11.22

simplejson==3.16.0
djangorestframework == 3.9.4

MarkupSafe == 1.1.1
Jinja2==2.10.1

coreschema==0.0.4
itypes==1.1.0
uritemplate==3.0.0

setuptools_scm==3.3.2
setuptools==40.8.0
pytest_runner==5.0
certifi==2019.6.16
urllib3==1.25.2
chrdet==3.0.3
requests==2.22.0

coreapi==2.3.3
openapi-codec==1.3.1
django-rest-swagger == 2.2.0

二、创建一个公共的swagger_schema.py

#-*- coding:UTF-8 -*-

import yaml
from urlparse import urljoin
from rest_framework.compat import coreapi
from rest_framework.schemas.generators import is_custom_action
from rest_framework.schemas.inspectors import AutoSchema

class CustomViewSchema(AutoSchema):
    def get_link(self, path, method, base_url):

        if hasattr(self.view, ‘action‘):
            action = self.view.action
        else:
            action = ‘‘

        if not is_custom_action(action):
            return super(CustomViewSchema, self).get_link(path, method, base_url)

        fields = self.get_path_fields(path, method)

        yaml_doc = None
        if self.view and self.view.__doc__:
            try:
                yaml_doc = yaml.load(self.view.__doc__)
            except:
                yaml_doc = None

        if yaml_doc and ‘desc‘ in yaml_doc:
            desc = yaml_doc.get(‘desc‘, ‘‘)
            _method_desc = desc
            params = yaml_doc.get(‘parameters‘, [])
            for i in params:
                _name = i.get(‘name‘)
                _desc = i.get(‘desc‘)
                _required = i.get(‘required‘, True)
                _type = i.get(‘type‘)
                _location = i.get(‘location‘, ‘query‘)
                f = coreapi.Field(
                    name=_name,
                    location=_location,
                    required=_required,
                    description=_desc,
                    type=_type
                )
                fields.append(f)
        else:
            _method_desc = self.view.__doc__ if self.view and self.view.__doc__ else ‘‘
            fields += self.get_serializer_fields(path, method)

        fields += self.get_pagination_fields(path, method)
        fields += self.get_filter_fields(path, method)

        te = []
        for field in fields:
            if field.location in ‘query‘:
                te.append(field.location)

        if fields and any(te):
            encoding = self.get_encoding(path, method)
        else:
            encoding = None

        if base_url and path.startswith(‘/‘):
            path = path[1:]

        return coreapi.Link(
            url=urljoin(base_url, path),
            encoding=encoding,
            action=method.lower(),
            fields=fields,
            description=_method_desc
        )

 

三、在自己的django项目中的APP修改views

from common.swagger_schema import CustomViewSchema
from rest_framework.decorators import api_view,schema

@api_view([‘GET‘]) #可以改为POST方法等
@schema(CustomViewSchema())
def getfiles(request):
    """
    desc: 获取某个路
    parameters:
    - name: spath
      desc: 远程的地址，    
      type: string   #控制你输入的类型，比如字符串、数字等
      required: true  #控制参数是否为必选项
      location: query #可以修改为form等

    - name: ip
      desc: 远程ip
      type: string
      required: true
      location: query

    - name: port
      desc: 远程端口，
      type: string
      required: true
      location: query

    - name: username
      desc: 远程ip的用户
      type: string
      required: true
      location: query

    - name: password
      desc: 远程ip的密码
      type: string
      required: true
      location: query

    """
    spath = request.GET.get("spath",".")
    ip = request.GET.get("ip","")
    port = request.GET.get("port",22)
    username = request.GET.get("username","")
    password = request.GET.get("password","")
    return HttpResponse(‘get‘)

 

四、修改项目根目录下的setting

1、在  INSTALLED_APPS 中增加 

rest_framework_swagger 和 rest_framework

五、修改项目根目录下的url

from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title=‘jobapp API‘,renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
    url(r‘^admin/‘, admin.site.urls),
    url(r‘^app/‘, include(device_urls)),#这个是你自己创建的app 
    url(r‘^api-auth/‘, include(‘rest_framework.urls‘, namespace=‘rest_framework‘)),
    url(r‘^api/‘, schema_view),
]

 

做到这一步，使用runsever应该就可以出现swagger界面。但是公司使用的uwsgi启动项目的，因此还要继续往下走。
要使用uwsgi需要配置nginx的。

六、执行  python manage.py collectstatic 从setting中的INSTALLED_APPS 去收集static。
会出现一个目录collected_static。里面有三个文件：admin  rest_framework  rest_framework_swagger

七、在项目根目录下的setting下修改

STATIC_URL = ‘/static/‘
STATIC_ROOT = os.path.join(BASE_DIR, ‘collected_static‘)
STATICFILES_DIRS = (
    os.path.join(BASE_DIR, "static"),        
                    
)
八、在uwsgi.ini文件下增加

static-map = /static=/home/appuser/jobapp/collected_static