接口文档示例 | DRF

**简要描述：** 

- 企业信息统计接口

**请求URL：** 
- ` http://127.0.0.1/ztx_data/v1/ep_info `
  
**请求方式：**
- GET 

**参数：** 

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|username |是  |string |用户名   |
|password |是  |string | 密码    |


 **返回示例**
``` json
// 成功响应
// 分页数据
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {
        "count": 28,
        "next": "http://127.0.0.1:8000/process_drf/?page=2&size=5",
        "previous": null,
        "results": [
            {
                "id": 13,
                "code": "process_13",
                "name": "企业门户",
                "remark": "",
                "sign": "0",
                "rto": null,
                "rpo": null,
                "state": "9",
                "sort": 4,
                "url": "/falconstor",
                "type": "falconstor",
                "color": "#e7505a"
            },
            {
                "id": 14,
                "code": "2",
                "name": "mkl",
                "remark": "hehehehe",
                "sign": "0",
                "rto": 1,
                "rpo": 2,
                "state": "9",
                "sort": 5,
                "url": "/falconstor",
                "type": "falconstor",
                "color": "#32c5d2"
            },
        ]
    }
}
// 单条记录
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {
        "id": 15,
        "code": "asd",
        "name": "sadad",
        "remark": "hahaha",
        "sign": "0",
        "rto": 2,
        "rpo": 3,
        "state": "1",
        "sort": 6,
        "url": "/falconstor",
        "type": "falconstor",
        "color": "#8e44ad"
    }
}
// POST
{
    "code": 201,
    "msg": "success",
    "errors": {},
    "data": {
        "id": 42,
        "code": "s",
        "name": "a",
        "remark": null,
        "sign": null,
        "rto": null,
        "rpo": null,
        "state": null,
        "sort": null,
        "url": "",
        "type": null,
        "color": ""
    }
}
// PUT
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {
        "id": 15,
        "code": "asd",
        "name": "mkl",
        "remark": "hahaha",
        "sign": "0",
        "rto": 2,
        "rpo": 3,
        "state": "1",
        "sort": 6,
        "url": "/falconstor",
        "type": "falconstor",
        "color": "#8e44ad"
    }
}
// DELETE
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {}
}
```
 **返回参数说明** 

|参数名|类型|说明|
|:-----  |:-----|-----                           |
|groupid |int   |用户组id，1：超级管理员；2：普通用户  |

 **备注** 

- 返回企业信息

| 错误码  | 错误解释  |
| ------------ | ------------ |
|  401 | 用户认证失败  |
|  403 | 权限校验失败  |
|  422 |  入参错误 |

- 返回示例
> POST请求

```json
{
    "code": 422,
    "msg": "入参错误",
    "errors": {
        "code": "This field may not be blank.",
        "name": "This field may not be blank."
    },
    "data": {}
}
```
> GET请求

```json
{
    "code": 422,
    "msg": "error",
    "errors": {
        "param": "Process matching query does not exist."
    },
    "data": {}
}

项目示例：

# @file           :views.py
# @description    :企业信息应用视图
# @date           :2021/07/01 18:02:52
# @author         :miaokela
# @version        :1.0
from rest_framework.generics import GenericAPIView
from django.http import Http404

from company import extra_models
from ZTXDMS.utils.response import APIResponse
from ZTXDMS.utils.pagination import RestPagination
from company.serializers import (
    CompanyListSerializer,
    CompanyDetailSerializer,
    AgencyListSerializer,
    AgencyDetailSerializer,
)
from company.conf import sqls


class CompanyAPIView(GenericAPIView):
    queryset = extra_models.QccQccCrawler.objects.using('company').exclude(is_delete='1').order_by('-update_time')
    serializer_class = CompanyListSerializer
    pagination_class = RestPagination

    def get(self, request):
        queryset = self.get_queryset()
        if request.query_params:
            company_name = request.query_params.get('company_name', '').strip()
            queryset = queryset.filter(company_name__contains=company_name)
            # TODO 数据库没有的数据从企查查站点采集

        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)

        ser = self.get_serializer(page, many=True)

        return APIResponse(code=200, data=ser.data)


class CompanyDetailAPIView(GenericAPIView):
    queryset = extra_models.QccQccCrawler.objects.using('company').exclude(is_delete='1').order_by('-update_time')
    lookup_field = 'id'

    def delete(self, request, id):
        try:
            qcc = self.get_object()
            qcc.is_delete = '1'
            qcc.save()
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['记录不存在，删除失败。']})

        return APIResponse(code=200)

    def get(self, request, id):
        try:
            ser = CompanyDetailSerializer(self.get_object())
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['记录不存在。']})
        else:
            return APIResponse(code=200, data=ser.data)


class AgencyAPIView(GenericAPIView):
    queryset = list(extra_models.Quanguo.objects.using('company').raw(sqls.AGENCY_JOIN_COMPANY))
    serializer_class = AgencyListSerializer
    pagination_class = RestPagination

    def get(self, request):
        queryset = self.get_queryset()
        if request.query_params:
            agency = request.query_params.get('agency', '').strip()
            city = request.query_params.get('city', '').strip()

            params_filters = []
            if agency:
                params_filters.append('qg.agency LIKE "%%{0}%%"'.format(agency))
            if city:
                params_filters.append('qg.city LIKE "{0}%%"'.format(city))
            filter_string = ' AND '.join(params_filters)
            if filter_string:
                c_sql = ' AND '.join([sqls.AGENCY_JOIN_COMPANY, filter_string])
                queryset = list(extra_models.Quanguo.objects.using('company').raw(c_sql))
        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)

        ser = self.get_serializer(queryset, many=True)

        return APIResponse(code=200, data=ser.data)


class AgencyDetailAPIView(GenericAPIView):
    queryset = list(extra_models.Quanguo.objects.using('company').raw(sqls.AGENCY_JOIN_COMPANY))
    lookup_field = 'id'

    def delete(self, request, id):
        try:
            agency = self.get_object()
            agency.is_delete = '1'
            agency.save()
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['记录不存在，删除失败。']})

        return APIResponse(code=200)

    def get(self, request, id):
        try:
            ser = AgencyDetailSerializer(self.get_object())
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['记录不存在。']})
        else:
            return APIResponse(code=200, data=ser.data)

    def get_object(self):
        """
        无法使用self.get_object() List不具备get()方法
        """
        try:
            # Perform the lookup filtering.
            lookup_url_kwarg = self.lookup_url_kwarg or self.lookup_field

            assert lookup_url_kwarg in self.kwargs, (
                    'Expected view %s to be called with a URL keyword argument '
                    'named "%s". Fix your URL conf, or set the `.lookup_field` '
                    'attribute on the view correctly.' %
                    (self.__class__.__name__, lookup_url_kwarg)
            )

            filter_kwargs = {self.lookup_field: self.kwargs[lookup_url_kwarg]}
            sql = ' '.join([
                sqls.AGENCY_JOIN_COMPANY, 'AND qg.id={id}'.format(**filter_kwargs)
            ])
            agency = extra_models.Quanguo.objects.using('company').raw(sql)[0]
        except Exception as e:
            print(e)
            raise Http404()
        else:
            return agency

from django.conf.urls import url
from company import views


urlpatterns = [
    url(r'companies/$', views.CompanyAPIView.as_view()),
    url(r'companies/(?P<id>\d+)$', views.CompanyDetailAPIView.as_view()),
    url(r'agencies/$', views.AgencyAPIView.as_view()),
    url(r'agencies/(?P<id>\d+)$', views.AgencyDetailAPIView.as_view()),
]

# @file           :serializers.py
# @description    :自定义序列化器
# @date           :2021/07/01 17:42:06
# @author         :miaokela
# @version        :1.0
from rest_framework import serializers

from rest_framework import serializers


class CompanyListSerializer(serializers.Serializer):
    """
    列表页字段序列化：
        - 企业名称
        - 企业法人
        - 注册资本
        - 组织机构代码
        - 公司行业
        - 公司类型
    """
    id = serializers.IntegerField()
    company_name = serializers.CharField()
    legal_representative = serializers.CharField()
    registered_capital = serializers.CharField()
    organization_code = serializers.CharField()
    industry = serializers.CharField()
    is_agency = serializers.CharField()


class CompanyDetailSerializer(serializers.Serializer):
    """
    详情页字段序列化：
        - 企业名称
        - 统一机构信用代码
        - 法定代表人
        - 工商注册号
        - 注册资本
        - 纳税人识别号
        - 实缴资本
        - 组织机构代码
        - 营业期限自
        - 营业期限至
        - 登记状态
        - 注册机关
        - 注册地址
        - 公司类别
    """
    id = serializers.IntegerField()
    company_name = serializers.CharField()
    unified_social_credit_code = serializers.CharField()
    legal_representative = serializers.CharField()
    business_registration_number = serializers.CharField()
    registered_capital = serializers.CharField()
    taxpayer_identification_number = serializers.CharField()
    paid_in_capital = serializers.CharField()
    organization_code = serializers.CharField()
    operating_period_std = serializers.CharField()
    operating_period_edt = serializers.CharField()
    operating_status = serializers.CharField()
    registration_authority = serializers.CharField()
    registered_address = serializers.CharField()
    is_agency = serializers.CharField()


class AgencyListSerializer(serializers.Serializer):
    """
    代理公司列表序列化器:
        - 代理公司
        - 组织机构代码
        - 企业法人
        - 地区
        - 业务联系人
        - 业务联系电话
    """
    id = serializers.IntegerField()
    society_code = serializers.CharField()
    agency = serializers.CharField()
    liaison = serializers.CharField()
    contact_information = serializers.CharField()
    address = serializers.CharField()
    institutional = serializers.CharField()
    put_time = serializers.CharField()
    city = serializers.CharField()

 
class AgencyDetailSerializer(serializers.Serializer):
    """
    代理公司列表序列化器:
        - 业务联系人
        - 业务联系电话
        - 企业名称
        - 统一机构信用代码
        - 法定代表人
        - 工商注册号
        - 注册资本
        - 纳税人识别号
        - 实缴资本
        - 组织机构代码
        - 营业期限自
        - 营业期限至
        - 登记状态
        - 注册机关
        - 注册地址
        - 公司类别
    """
    id = serializers.IntegerField()
    company_name = serializers.CharField()
    unified_social_credit_code = serializers.CharField()
    legal_representative = serializers.CharField()
    business_registration_number = serializers.CharField()
    registered_capital = serializers.CharField()
    taxpayer_identification_number = serializers.CharField()
    paid_in_capital = serializers.CharField()
    organization_code = serializers.CharField()
    operating_period_std = serializers.CharField()
    operating_period_edt = serializers.CharField()
    operating_status = serializers.CharField()
    registration_authority = serializers.CharField()
    registered_address = serializers.CharField()
    liaison = serializers.CharField()
    contact_information = serializers.CharField()
    is_agency = serializers.CharField()

# @file           :exception.py
# @description    :自定义错误相应
# @date           :2021/07/01 17:26:14
# @author         :miaokela
# @version        :1.0
from django.http import Http404
from rest_framework import exceptions, views
from django.core.exceptions import PermissionDenied
from rest_framework.response import Response


def exception_handler(exc, context):
    """
    自定义 exception_handler 错误信息返回
    Returns the response that should be used for any given exception.

    By default we handle the REST framework `APIException`, and also
    Django's built-in `Http404` and `PermissionDenied` exceptions.

    Any unhandled exceptions may return `None`, which will cause a 500 error
    to be raised.
    """
    if isinstance(exc, Http404):
        exc = exceptions.NotFound()
    elif isinstance(exc, PermissionDenied):
        exc = exceptions.PermissionDenied()

    if isinstance(exc, exceptions.APIException):
        headers = {}
        if getattr(exc, 'auth_header', None):
            headers['WWW-Authenticate'] = exc.auth_header
        if getattr(exc, 'wait', None):
            headers['Retry-After'] = '%d' % exc.wait

        if isinstance(exc.detail, (list, dict)):
            if isinstance(exc.detail, list):
                errors = exc.detail
            else:
                errors = {k: v[0] for k, v in exc.detail.items()}
        else:
            errors = exc.detail

        views.set_rollback()
        return Response({
            'code': 400, 'msg': 'failed', 'errors': errors, 'data': {}
        }, status=exc.status_code, headers=headers)

    return None

# @file           :pagination.py
# @description    :自定义分页
# @date           :2021/07/01 17:23:46
# @author         :miaokela
# @version        :1.0
from rest_framework.pagination import LimitOffsetPagination
from ZTXDMS.utils.response import APIResponse
from collections import OrderedDict


class RestPagination(LimitOffsetPagination):
    default_limit = 20  # 默认从第一条开始(offset=0),往后5条为一页
    limit_query_param = 'limit'
    offset_query_param = 'offset'
    max_limit = 40

    def get_paginated_response(self, data):
        return APIResponse(code=200, data=OrderedDict([
            ('count', self.count),
            ('next', self.get_next_link()),
            ('previous', self.get_previous_link()),
            ('results', data)
        ]))

# @file           :response.py
# @description    :重写DRF Response相应类
# @date           :2021/07/01 17:12:51
# @author         :miaokela
# @version        :1.0
from rest_framework.response import Response


class APIResponse(Response):
    def __init__(self, code=200, msg='success', data=None, status=None, headers=None, errors=None, **kwargs):
        errors = {k: v[0] for k, v in errors.items()} if errors else {}

        dic = {'code': code, 'msg': msg, "errors": errors}
        if data:
            dic = {
                'code': code,
                'msg': msg,
                'data': data,
            }
        dic.update(kwargs)
        super().__init__(data=dic, status=status, headers=headers)

### 简要描述：

> 企业信息统计接口

### 获取多企业信息

**请求URL：**

- `http://127.0.0.1:8000/v1/companies/`

**请求方式：**

- GET

**请求参数：**

|    参数名    | 必选 |  类型  | 默认值 |   说明   |
| :----------: | :--: | :----: | :----: | :------: |
| company_name |  否  | string |   无   | 企业名称 |

**响应参数**

|        参数名        |  类型  | 说明                                 |
| :------------------: | :----: | ------------------------------------ |
|          id          |  int  | 企业ID                               |
|     company_name     | string | 企业名称                             |
| legal_representative | string | 法人代表                             |
|  registered_capital  | string | 注册资本                             |
|  organization_code  | string | 组织机构代码                         |
|       industry       | string | 行业                                 |
|      is_agency      | string | 公司类别（"1"：代理机构，"0"：其它） |

**响应结果示例**

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "count": 1404,
        "next": "http://114.67.84.76/v1/companies/?limit=20&offset=20",
        "previous": null,
        "results": [
            {
                "id": 96,
                "company_name": "郑州泽正生物科技有限公司",
                "legal_representative": "张洋洋",
                "registered_capital": "500万元人民币",
                "organization_code": "MA9GXRYX-8",
                "industry": "医药制造业",
                "is_agency": "0"
            },
            ...  // 默认20条记录
        ]
    }
}
```

### 获取单企业信息

**请求URL：**

- `http://127.0.0.1:8000/v1/companies/{:id}`

**请求方式：**

- GET

**请求参数：**

| 参数名 | 必选 | 类型 | 默认值 |  说明  |
| :----: | :--: | :--: | :----: | :----: |
|   id   |  是  | int |   无   | 企业ID |

**响应参数**

|             参数名             |  类型  | 说明                                 |
| :----------------------------: | :----: | ------------------------------------ |
|               id               |  int  | 企业ID                               |
|          company_name          | string | 企业名称                             |
|   unified_social_credit_code   | string | 统一社会信用代码                     |
|      legal_representative      | string | 法人代表                             |
|  business_registration_number  | string | 工商注册号                           |
|       registered_capital       | string | 注册资本                             |
| taxpayer_identification_number | string | 纳税人识别号                         |
|        paid_in_capital        | string | 实缴资本                             |
|       organization_code       | string | 组织机构代码                         |
|      operating_period_std      | string | 营业期限自                           |
|      operating_period_edt      | string | 营业期限至                           |
|        operating_status        | string | 登记状态                             |
|     registration_authority     | string | 注册机关                             |
|       registered_address       | string | 注册地址                             |
|           is_agency           | string | 公司类别（"1"：代理机构，"0"：其它） |

**响应结果示例**

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 10,
        "company_name": "宜山县妇联巾帼经济服务部",
        "unified_social_credit_code": "-",
        "legal_representative": "陆美鲜",
        "business_registration_number": "4527021002240",
        "registered_capital": "2万元人民币",
        "taxpayer_identification_number": "-",
        "paid_in_capital": "-",
        "organization_code": "-",
        "operating_period_std": "3199-06-22",
        "operating_period_edt": "无固定期限",
        "operating_status": "注销",
        "registration_authority": "河池市宜州区市场监督管理局",
        "registered_address": "庆远解放路5号查看地图附近企业",
        "is_agency": "0"
    }
}
```

### 删除企业信息

**请求URL：**

- `http://127.0.0.1:8000/v1/companies/{:id}`

**请求方式：**

- DELETE

**请求参数：**

| 参数名 | 必选 | 类型 | 默认值 |  说明  |
| :----: | :--: | :--: | :----: | :----: |
|   id   |  是  | int |   无   | 企业ID |

**响应参数**

| 参数名 | 类型 | 说明 |
| :----: | :--: | ---- |
|   无   |  无  | 无   |

**响应结果示例**

```json
{
    "code": 200,
    "msg": "success",
    "errors": {}
}
```

### 简要描述

> 全局响应与状态码

### 状态码

| 状态码 |     描述     |
| :----: | :----------: |
|  200  |   成功响应   |
|  404  |  记录不存在  |
|  422  | 参数校验失败 |

### 成功响应

```json
{
    "code": 200,
    "msg": "success",
    "data": {}
}
```

### 错误响应

* 新增/修改校验失败

```json
{
    "code": 422,
    "msg": "failed",
    "errors": {
        "code": "This field may not be blank.",
        "name": "This field may not be blank."
    },
    "data": {}
}
```

* 删除/查询记录不存在

```json
{
    "code": 404,
    "msg": "failed",
    "errors": {
        "id": "记录不存在，删除失败。"
    }
}
```