# 宝马OCR系统开发规范


## 代码规范

1. 参考 [python_specification.md](python_specification.md)
2. 帐号、密码严禁提交到git仓中
3. 参与开发前请阅读[十二要素应用宣言](https://12factor.net/zh_cn/)


## 接口文档

接口文档使用`openapi`规范书写， 可以参考[demo](http://editor.swagger.io/)以获取直观感受。

目前，接口文档写在代码中， 并通过脚本将代码中的文档提取出来, 示例如下。


1. 编写文档

    ```python
    class UserInfoView(APIView):
        def get(self, request):
            user_info = serializers.staff_detail.dump(request.user).data
            return APIResponse.ok(user_info)
    
        get.openapi_doc = '''
          summary: 获取个人信息
          tags:
            - 帐号
          responses:
            200:
              description: ok
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      meta:
                        $ref: '#/components/schemas/ApiResponseMeta'
                      data:
                        $ref: '#/components/schemas/AccountInfoDetail'
        '''
    
    
    ```

2. 提取接口文档

    ```
    $: python manage.py generate_api_doc -o ../docs/main.yaml
    api doc generated succssfully: ../docs/main.yaml
    ```

3. 校对接口文档

    ```
    $: python manage.py validate_api_doc ../docs/main.yaml 
    ok
    ```

4. 查看接口文档

    * 方法1: 粘贴到[online editor](http://editor.swagger.io/)中查看
    * 方法2: 安装 https://bitbucket.org/abrahamL/openapi_toolset.git
    
        ```
        $: cd docs
        $: ls
        main.yaml
        $: python -m openapi_toolset
          * Serving Flask app "openapi_toolset" (lazy loading)
          * Environment: production
            WARNING: Do not use the development server in a production environment.
            Use a production WSGI server instead.
          * Debug mode: off
          * Running on http://127.0.0.1:9090/ (Press CTRL+C to quit)
        ```

      浏览器访问http://127.0.0.1:9090即可查看文档