基于drf_yasg插件 生成开发文档(概要设计和详细设计)

最新推荐文章于 2023-06-16 07:53:38 发布
最新推荐文章于 2023-06-16 07:53:38 发布
阅读量785 收藏 6
点赞数 1
分类专栏： python web 实际解决方案 文章标签： python django
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_43500579/article/details/113244806
版权

问题

对于开发者，编写文档是非常头疼的问题。但是又是项目交付必须要的部分。

说明

  1. 此文是基于drf_yasg插件生成详细设计和概要设计文档，但只是框架性的，以及接口部分可以自动生成，个性化内容还需要自己去填充。

  2. 输出格式为markdown格式，还需要编辑后，转换为pdf格式，形成文档。

代码部分

# -*- coding: UTF-8 -*-
# Desc   : 项目输出api文档(详细设计文档和概要设计)
import time
import requests


def magic_api(markdown_path: str, swagger_url: str):
    """
    将api输出为markdown文档
    :param markdown_path: markdown输出路径
    :param swagger_url: swagger的json数据请求url
    :return:
    """
    res = requests.get(swagger_url)
    swagger_info = res.json()
    # title = swagger_info['info']['title']
    # TODO 修改项目名称
    project_name='项目名称'
    title_txt = '# %s 详细设计文档' % project_name
    base_url = swagger_info['basePath']
    # 文档前部分
    files_list=[]
    files_list.append('- 文档时间：%s'%(time.strftime('%Y-%m-%d'),))
    files_list.append('## 1 简介')
    files_list.append('### 1.1 目的')
    files_list.append(' 本文档旨在说明%s各模块的总体设计思路，为软件编程和系统维护提供依据。本说明书的预期读者为系统设计人员、软件开发人员、软件测试人员和项目评审人员。'%(project_name,))
    files_list.append('### 1.2 范围')
    # TODO 修改模块组成
    files_list.append(' 对%s中的各个模块进行详细的描述，包括%s。'%(project_name,'模块组成'))
    files_list.append('### 1.3 缩略语')
    files_list.append("|缩略语|英文全称|中文解释|")
    files_list.append("|:-:|:-:|:-:|")
    files_list.append('|%s|' % '|'.join(['','','']))

    files_list.append('## 2 系统架构')
    files_list.append('## 3 功能结构')
    files_list.append('## 4 各模块详细设计')
    # 文档结尾部分
    ends_list=[]
    ends_list.append('## 5	数据流详细设计')
    ends_list.append('### 5.1	数据源')
    ends_list.append('### 5.2	数据流转')
    ends_list.append('## 6	系统部署描述')
    ends_list.append('## 7	参考资料')

    # 文档api部分
    words_list = []
    model_tags={
    	# TODO
    	# 模块名：模块含义
        'auth':'登录模块',
    }
    # 遍历url
    for k, v in swagger_info['paths'].items():
        url = base_url + k
        # tags为模块名称占位符
        files_text = [url, 'tags']
        files_text.append("\n")
        files_text.append("#### %s" % url)

        for method, values in v.items():
            if method == 'parameters':
                continue
            files_text.append("- **请求方法：%s**" % method)
            files_text.append("接口用途：%s" % values['description'])
            # 模块名称
            files_text[1] = values['tags'][0]
            # 获取请求参数
            files_text.append('- 请求参数')
            files_text.append("|参数名称|参数含义|数据类型|是否必须|枚举数据|默认值|备注|")
            files_text.append("|-|-|:-:|:-:|:-:|:-:|-|")
            # 处理参数
            for parameter in values['parameters']:
                parm_list = []
                # 处理结构化(object类型)的参数
                if parameter['name'] == 'data':
                    schema = parameter['schema']

                    for zi_parm, zi_value in schema['properties'].items():
                        schema_list = []
                        schema_list.append(zi_parm)
                        schema_list.append(zi_value['description'])

                        schema_list.append(zi_value['type'])
                        schema_list.append('')
                        schema_list.append('')
                        schema_list.append('')
                        schema_list.append('')
                        parm_list.append(schema_list)
                        # print('参数名称:', zi_parm, '参数描述:', zi_value['description'], '参数类型:', zi_value['type'])
                else:
                    parm_list.append(parameter['name'])
                    parm_list.append(parameter['description'])
                    parm_list.append(parameter['type'])
                    parm_list.append('是' if parameter.get('required') else '否')
                    parm_list.append(str(parameter.get('enum')) if parameter.get('enum') else '')
                    parm_list.append(str(parameter.get('default')) if parameter.get('default') else '')
                    parm_list.append('')

                for i in parm_list:
                    if isinstance(i, list):
                        files_text.append('|%s|' % '|'.join(i))
                if parm_list and parm_list[0]:
                    if isinstance(parm_list[0], str):
                        files_text.append('|%s|' % '|'.join(parm_list))
            # 响应
            files_text.append('- 响应结果')
            files_text.append("|响应状态码|描述|返回值示例|备注|")
            files_text.append("|:-:|:-:|:-:|:-:|")
            for res_key, res_value in values['responses'].items():
                resp_list = []
                resp_list.append(res_key)
                resp_list.append(res_value['description'])
                examples = res_value.get('examples')
                example_txt = ''
                if examples:
                    for k, v in examples.items():
                        example_txt += k + ' : '
                        example_txt += str(v)
                resp_list.append(example_txt)
                resp_list.append('')
                files_text.append('|%s|' % '|'.join(resp_list))
        words_list.append(files_text)
    words_list.sort(key=lambda x: x[1])
    with open(markdown_path, 'w', encoding='utf-8') as fw:
        fw.write(title_txt + '\n\n')
        fw.write('\n'.join(files_list)+'\n')
        model_name = []
        for url in words_list:
            if url[1] not in model_name:
                chinese_model_name=model_tags.get(url[1])
                if not chinese_model_name:
                    chinese_model_name=url[1]
                fw.write('### %s%s' % (chinese_model_name, '\n'))
                model_name.append(url[1])
            fw.write('\n'.join(url[2:]) + '\n')
        fw.write('\n'.join(ends_list))


def outline_design(markdown_path: str, swagger_url: str):
    """
    将api输出为markdown文档，作为概要设计
    :param markdown_path: markdown输出路径
    :param swagger_url: swagger的json数据请求url
    :return:
    """
    res = requests.get(swagger_url)
    swagger_info = res.json()
    # title = swagger_info['info']['title']
    project_name = '项目名称'
    title_txt = '# %s 概要设计文档' % project_name
    base_url = swagger_info['basePath']
    # 文档前部分
    files_list = []
    files_list.append('- 文档时间：%s' % (time.strftime('%Y-%m-%d'),))
    files_list.append('## 1 简介')
    files_list.append('### 1.1 文档目标')
    files_list.append('1. 本文档旨在说明%s系统的总体设计思路，为软件编程和系统维护提供依据。'%(project_name,))
    files_list.append('2. 本文描述%s系统结构，给出模块的边界。'%(project_name,))
    files_list.append('3. 此文档从构架方面对%s系统进行综合概述，记录并表述已在构架方面对目标系统作出的重要决定。'%(project_name,))
    files_list.append('4. 此文档针对%s的需求文档进行业务架构建模，并对后续的详细设计和Coding提供指导和参照。'%(project_name,))
    files_list.append('### 1.2 适用对象')
    files_list.append('本文适合相关的产品、研发、测试人员等相关人员阅读。')
    files_list.append('1. 产品经理：了解此系统的功能架构和模块设计。')
    files_list.append('2. 开发工程师：遵循本文档进行详细设计和后续的编码工作')
    files_list.append('3. 测试人员：了解此系统的功能架构和模块设计，指导测试用例编写。')
    files_list.append('### 1.3 范围')
    files_list.append("本文档主要涉及：")
    files_list.append("1. 根据产品需求及原型设计进行功能模块划分，本系统模块主要包括大屏首页，遥感底图，图斑模块，用户模块，报表模块。")
    files_list.append("2. 对系统的各个模块进行详细的描述，包括各个功能模块间的关系描述，以及模块对外提供接口的详细描述。")
    files_list.append("本文档不涉及以下内容：")
    files_list.append("1. 不涉及各个模块内部详细功能，此部分请参考《%s系统详细设计》。"%(project_name,))

    files_list.append('### 1.4 参考资料')
    files_list.append('### 1.5 术语列表')
    files_list.append("|术语(缩写)|解释|")
    files_list.append("|:-:|:-:|")
    files_list.append('|%s|' % '|'.join(['','']))
    files_list.append('## 2. 总体技术方案')
    files_list.append('### 2.1 设计概述')
    files_list.append('1. 系统从功能实现的角度主要分为')
    files_list.append('2. 系统从页面展示角度主要分为')
    files_list.append('### 2.2 总体架构')
    files_list.append('#### 2.2.1 软件结构图')
    files_list.append('#### 2.2.2 功能结构图')
    files_list.append('#### 2.2.3 接口说明')

    # 文档结尾部分
    ends_list = []
    ends_list.append('#### 2.2.4 数据流分析')
    ends_list.append('##### 2.2.4.1 数据源')
    ends_list.append('##### 2.2.4.2 数据流转')
    ends_list.append('数据的处理分为三个阶段：数据获取、数据处理、数据入库。')
    ends_list.append('（1）数据获取')
    ends_list.append('（2）数据处理')
    ends_list.append('（3）数据及入库')
    ends_list.append('##### 2.2.4.3 流程图')

    # 文档api部分
    words_list = []
    model_tags = {
    	# TODO 
        'auth': '登录模块',
    }
    # 遍历url
    for k, v in swagger_info['paths'].items():
        url = base_url + k
        # tags为模块名称占位符
        files_text = [url, 'tags']
        files_text.append("\n")
        files_text.append("###### %s" % url)

        for method, values in v.items():
            if method == 'parameters':
                continue
            files_text.append("- **请求方法：%s**" % method)
            files_text.append("接口用途：%s" % values['description'])
            # 模块名称
            files_text[1] = values['tags'][0]
            # 获取请求参数
            files_text.append('- 请求参数')
            files_text.append("|参数名称|参数含义|数据类型|是否必须|枚举数据|默认值|备注|")
            files_text.append("|-|-|:-:|:-:|:-:|:-:|-|")
            # 处理参数
            for parameter in values['parameters']:
                parm_list = []
                # 处理结构化(object类型)的参数
                if parameter['name'] == 'data':
                    schema = parameter['schema']

                    for zi_parm, zi_value in schema['properties'].items():
                        schema_list = []
                        schema_list.append(zi_parm)
                        schema_list.append(zi_value['description'])

                        schema_list.append(zi_value['type'])
                        schema_list.append('')
                        schema_list.append('')
                        schema_list.append('')
                        schema_list.append('')
                        parm_list.append(schema_list)
                        # print('参数名称:', zi_parm, '参数描述:', zi_value['description'], '参数类型:', zi_value['type'])
                else:
                    parm_list.append(parameter['name'])
                    parm_list.append(parameter['description'])
                    parm_list.append(parameter['type'])
                    parm_list.append('是' if parameter.get('required') else '否')
                    parm_list.append(str(parameter.get('enum')) if parameter.get('enum') else '')
                    parm_list.append(str(parameter.get('default')) if parameter.get('default') else '')
                    parm_list.append('')

                for i in parm_list:
                    if isinstance(i, list):
                        files_text.append('|%s|' % '|'.join(i))
                if parm_list and parm_list[0]:
                    if isinstance(parm_list[0], str):
                        files_text.append('|%s|' % '|'.join(parm_list))
            # 响应
            files_text.append('- 响应结果')
            files_text.append("|响应状态码|描述|返回值示例|备注|")
            files_text.append("|:-:|:-:|:-:|:-:|")
            for res_key, res_value in values['responses'].items():
                resp_list = []
                resp_list.append(res_key)
                resp_list.append(res_value['description'])
                examples = res_value.get('examples')
                example_txt = ''
                if examples:
                    for k, v in examples.items():
                        example_txt += k + ' : '
                        example_txt += str(v)
                resp_list.append(example_txt)
                resp_list.append('')
                files_text.append('|%s|' % '|'.join(resp_list))
        words_list.append(files_text)
    words_list.sort(key=lambda x: x[1])
    with open(markdown_path, 'w', encoding='utf-8') as fw:
        fw.write(title_txt + '\n\n')
        fw.write('\n'.join(files_list) + '\n')
        model_name = []
        for url in words_list:
            if url[1] not in model_name:
                chinese_model_name = model_tags.get(url[1])
                if not chinese_model_name:
                    chinese_model_name = url[1]
                fw.write('##### %s%s' % (chinese_model_name, '\n'))
                model_name.append(url[1])
            fw.write('\n'.join(url[2:]) + '\n')
        fw.write('\n'.join(ends_list))

if __name__ == '__main__':
	# drf_yasg接口url
    url = 'http://172.27.11.200:8001/redoc/?format=openapi'
	# 详细设计文档
    # magic_api('./test_api.md', url)
    # 概要设计文档
    outline_design('./outline_design.md', url)
徒余途
关注
  • 1
    点赞
  • 踩
  • 6
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
用doxygen自动生成详细设计文档
stepbystep_1_1的专栏
03-13 2768
以前写程序的时候就是从开始就是编码，调试通过了就算结束了。工作了以后这个规则就变了，先要写概要设计文档，再详细文档，再编码，再测试，再返工。。。。。。当后面测试返工调整的时候与以前设计的思路可能已经不一样了，这时再去修改文档感觉就没有动力了。所以就想了一招用doxygen来成生详细设计文档，这样在修改代码的时候，把注释修改一下，再生成就OK了，这样文档也可以跟着代码在更新。 doxygen
数据库设计文档自动生成工具.rar
06-11
数据库文档自动生成工具，根据数据库自动生成doc文档，支持sqlserver mysql 其他的后续加入
怎么写设计文档–概要设计
laiconglin的专栏
07-29 853
在需求分析进行完成之后 项目进入设计阶段。在设计阶段需要编写设计文档。开发过程中的设计文档 分为：  概要设计 和 详细设计 2个部分。概要设计 是将杂系统按功能进行 模块划分、建立层次结构及调用关系、包括数据特征描述 ,以及界面等。 概要设计 是由架构师和每个开发者共同完成的
自动生成C语言详细设计文档工具
04-11
================================================================ cdocgen - A C-file documentation generator ================================================================ cdocgen是一个功能强大的自文档化工具，可以根据doxygen风格的注释， 生成visio格式的流程图，并可以自动插入到详细设计中。
项目概要设计书一般设计方法
潇湘博客
04-29 2549
             做软件到一定层次了，就要考虑到设计了，设计了很久，就是不系统，系统的设计需要一个记录，记录就用文档，那么对项目所有包括技术上的设计都记录下来，我们就可以理解为软件的概要设计了。           在需求明确、准备开始编码之前，要做概要设计，而详细设计可能大部分公司没有做，有做的也大部分是和编码同步进行，或者在编码之后。因此，对大部分的公司来说，概要设计文档是唯一的设
利用AIGC生成软件的设计文档
XDevelop
06-16 1327
通过AI大模型，我们确实可以利用文档的自动生成来减少文档工作。然而软件的文档并不是独立的，而是一组相关文档的集合。这就需要大量的AI提示词，并且这些提示词之间具有一定的逻辑关系。因此我们可以建立一个软件的设计元模型，充当AI提示词的作用，生成一致的文档体系。
drf-yasg-json-api:从Django Rest Framework JSON API端点自动生成SwaggerOpenAPI 2.0规范
05-08
drf-yasg-json-api- drf-yasg符合JSON API 从Django Rest Framework端点自动生成Swagger / OpenAPI 2.0 JSON API规范。 该软件包使和一起使用。 目录 filter查询参数 分页 额外的 支持drf-yasg swagger_auto_...
drf-yasg：从Django REST框架代码自动生成真正的SwaggerOpenAPI 2.0模式
02-05
3. 配置`urls.py`，引入`drf_yasg.views`中的`get_schema_view`，并将其添加到URL路由中。 4. 重新运行你的应用，访问配置好的URL，即可看到自动生成的Swagger UI界面。 **总结** `drf-yasg`为Django REST框架的...
基于Django和DRF开发的简易博客API源码
最新发布
03-25
项目概述：简易博客API，基于Python的Django框架和DRF（Django REST Framework）开发。该项目包含12个Python源码文件（.py），12个编译后的Python文件（.pyc），5个XML配置文件，1个Git忽略文件，1个IDE项目文件（....
Python库 | drf_spectacular-0.13.0-py2.py3-none-any.whl
02-16
1. **自动化API文档生成**：`drf_spectacular`的核心特性是它可以自动扫描你的DRF项目，基于你的视图、模型和序列化器自动生成OpenAPI规范。这极大地减少了手动编写和维护API文档的工作量。 2. **OpenAPI兼容**：...
JMeter插件详细设计说明书
04-25
JMeter插件详细设计说明书,开发插件的说明实例
系统详细设计文档模板
09-29
本模板纯净级别，且通用与几乎所有系统软件的详细设计，使用者可自定义或添加其他元素以丰富内容。如需改进，欢迎提出建议。谢谢
Python库 | drf-yasg-1.15.1.tar.gz
05-14
资源分类：Python库 所属语言：Python 资源全名：drf-yasg-1.15.1.tar.gz 资源来源：官方 安装方法：https://lanzao.blog.csdn.net/article/details/101784059
软件设计文档模板_MBT文档模型化生成工具——30倍效率文档撰写工程化方法
weixin_29093017的博客
01-15 477
MBT（A model based document builder）文档模型化生成工具用户手册——30倍效率文档撰写工程化方法1 简介在软件工程领域，工程文档通常主要包括实施方案、需求分析、软件设计、测试报告、验收大纲、用户手册等几种。这些文档中，通常要求内容丰富，能够体现整个软件工程大部分信息；易于理解，需要制作各种表格，绘制各种图形，包括UML图。可见，文档撰写的工作量巨大，需要有工具支撑...
自动设计文档生成
litingjun的专栏
12-31 1392
http://51cmm.csai.cn/casepanel/ST/No062.htm在传统的自控设计中，手工编写设计文档占去了设计人员相当多的时间和精力，是设计人员最不愿意做的事情之一。手工编写设计文档不但费时费力，更重要的是，难以保证所编写的设计文档和设计完全符合。对设计的每次更改，都会带来设计文档的更改甚至完全重新编写，浪费大量精力和时间。自动设计文档生成工具可以有效地解决这个难题。设计人员
软件需求，概要设计，详细设计（文档）怎么做，做什么？
热门推荐
好习惯成就伟大
02-25 2万+
写在前面 由于项目工作需要 ，需要提供《软件需求规格说明书》，《软件概要设计说明书》和《软件详细设计说明书》。所以这里整理学习一下相关文档需要的内容。文章并不设计对所有需求分析，概要设计和详细设计的详细描述。因为这其中的任何一点都可以单独提取出来成为软件工程学科中的一本书籍内容。 1 软件设计的整体流程： 软件需求分析阶段：输出了《软件需求规格说明书》，不涉及具体实现方法。用户能看得明白，开发人员也可据此进行下面的工作，搞清楚“要解决什么问题”。 概要设计阶段：确定软件系统的总体布局，各个子模块的功
咋写概要设计文档
qinzhihu的专栏
01-07 2063
写概要设计文档，是每个team leader或者研发组长必备的技能。 写好了，上可以报告给大经理，下可以演示给各个组员。 概要文档可以写成很多种样子，有不同的侧重点，但是 出不了下面所述的这个圈子，无非是更细，或者更多点而已。 1.总则 不同的公司，不同的项目，设计文档的形式和侧重点不一样。 但是不论什么文档，最终就是要解释三个问题： 是什么？ 干什么？ 怎么干
Django 关于drf_yasg Api文档使用示例
qq_43500579的博客
12-11 4714
Django 关于drf_yasg Api文档使用示例 配置 settings.py INSTALLED_APPS = [ ... 'drf_yasg', ... ] urls.py from rest_framework import permissions from drf_yasg.views import get_schema_view from drf_yasg import openapi schema_view = get_schema_view( o
DRF-接口文档-（三方drf-yasg）-（简单使用）: 使用自定义的认证类，使用jwt做token时，想要使用自动生成文档
weixin_46371752的博客
08-27 2610
使用jwt自定义的认证下，自动生成文档，django配置自动生成文档的同时，可以携带上token，使用drf-yags生成文档时配置上可以携带token
ModuleNotFoundError: No module named 'drf_yasg2.schema'
08-23
这个错误提示意味着您的代码中使用了一个名为'drf_yasg2.schema'的模块，但您的环境中没有安装该模块。 解决这个问题的步骤如下： 1. 确保您已经正确安装了 'drf_yasg2' 模块。您可以使用以下命令安装最新版本的该...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值