一键生成系统Word接口文档的基本思路和实现

已于 2024-02-07 16:58:32 修改
阅读量825 收藏 7
点赞数 8
文章标签： word java yapi 系统架构
于 2024-01-10 00:02:15 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_37978198/article/details/135492473
版权

基本思路

  1. 可以利用swagger提供的/v2/api-docs接口返回的数据结构，来获取系统接口信息，包括：请求参数、请求Url、响应数据、相应码等；
  2. 对返回的数据去做解析，来组装符合Freemarker模板的数据；
  3. 通过Freemarker生成系统接口文档；
  4. 为了让接口swagger规范，可以提供代码模板，一键生成代码。

基本实现

  1. 设计Word接口文档模板的基本板式和格式，在resources/templates/word中;
  2. 设计满足Word接口文档模板的实体类格式，相关Bean在/document/dto中;
  3. 使用代码模板一键生成系统功能接口，执行ApplicationTests.codeGeneration()方法即可
  4. 启动系统，解析/v2/api-docs接口返回数据，组装数据使其符合步骤1设计的文档模板
  5. 将word接口文档模板重命名为2003版的.xml文件；
  6. 用notepad++打开xml文件，点击 插件 -> XMl tools-> Pretty print(libXML)，格式化xml文件；
  7. 对数据进行变量替换，并将文件重名为.ftl文件
  8. 保持系统启动状态，ApiDocumentGenerateTest.handler()一键生成系统接口文档;
  9. 到resources/word下，查看生成的word接口文档
  10. 更新文档目录，补充接口描述，补充接口实例等
  11. github源码链接

数据解析工具类SwaggerApiDataHandlerUtil

package com.ocean.angel.tool.doucment.util;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.util.StrUtil;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONArray;
import com.alibaba.fastjson.JSONObject;
import com.ocean.angel.tool.doucment.dto.*;
import lombok.extern.slf4j.Slf4j;
import java.util.ArrayList;
import java.util.List;

@Slf4j
public class SwaggerApiDataHandlerUtil {

    /**
     * 将swagger /v2/api-docs接口返回的数据转化成标准数据
     * @param documentData
     * @param jsonString
     */
    public static void dataHandler(DocumentData documentData, String jsonString) {

        try {
            // 将字符串转换为JSON对象
            JSONObject jsonObject = JSONObject.parseObject(jsonString);

            // 文档标题
            if(StrUtil.isEmpty(documentData.getTitle())) {
                String title = jsonObject.getJSONObject("info").getString("title");
                documentData.setTitle(title);
            }

            // swagger definitions 数据
            JSONObject definitionsJSONObject = jsonObject.getJSONObject("definitions");

            // swagger paths 数据
            JSONObject paths = jsonObject.getJSONObject("paths");

            // 接口tags数据，用于定义文档的二级目录
            List<ApiTag> tags = tagsHandler(paths, definitionsJSONObject);
            documentData.setTags(tags);

        } catch (Exception e) {
            log.error("SwaggerApiDataHandlerUtil.dataHandler() error. {}", e.getMessage(), e);
        }
    }

    /**
     * Tags数据处理
     * @param pathsJSONObject
     * @return
     */
    private static List<ApiTag> tagsHandler(JSONObject pathsJSONObject, JSONObject definitionsJSONObject) {

        List<ApiTag> tags = new ArrayList<>();

        for (String path : pathsJSONObject.keySet()) {

            ApiData apiData = new ApiData();

            // 请求url
            apiData.setPath(path);

            JSONObject apiJSONObject = pathsJSONObject.getJSONObject(path);
            for(String type: apiJSONObject.keySet()) {

                // 请求方式
                apiData.setType(type);
                JSONObject apiDataJSONObject = apiJSONObject.getJSONObject(type);

                // 接口名称
                apiData.setName(apiDataJSONObject.getString("description"));

                // 接口tag
                apiData.setTag(apiDataJSONObject.getJSONArray("tags").getString(0));

                // 请求参数数据处理
                JSONArray parametersJSONArray = apiDataJSONObject.getJSONArray("parameters");
                requestParamHandler(parametersJSONArray, definitionsJSONObject, apiData);

                // 响应数据和响应码数据处理
                JSONObject responsesJSONObject = apiDataJSONObject.getJSONObject("responses");
                responseHandler(responsesJSONObject, definitionsJSONObject, apiData);

                // 数据组装，将api划归到tag下
                tagsDataHandler(tags, apiData);
            }
        }

        return tags;
    }

    /**
     * 请求参数处理
     * @param parametersJSONArray
     * @param definitionsJSONObject
     * @return
     */
    private static void requestParamHandler(JSONArray parametersJSONArray, JSONObject definitionsJSONObject, ApiData apiData) {

        List<ApiParam> list = new ArrayList<>();
        for (Object object : parametersJSONArray) {
            JSONObject jsonObject = (JSONObject) object;
            JSONObject schemaJSONObject = jsonObject.getJSONObject("schema");
            if(null == schemaJSONObject) {

                // 普通参数
                ApiParam apiParam = JSONObject.parseObject(JSON.toJSONString(object), ApiParam.class);
                list.add(apiParam);
            } else {

                // 对象参数
                String ref = schemaJSONObject.getString("$ref").replace("#/definitions/", "");
                JSONObject propertiesJSONObject = definitionsJSONObject.getJSONObject(ref).getJSONObject("properties");

                // 对象参数转换，对象参数不能再嵌套
                for (String name : propertiesJSONObject.keySet()) {
                    ApiParam apiParam = new ApiParam();
                    apiParam.setName(name);
                    apiParam.setType(propertiesJSONObject.getJSONObject(name).getString("type"));
                    apiParam.setDescription(propertiesJSONObject.getJSONObject(name).getString("description"));
                    apiParam.setRequired(false);
                    list.add(apiParam);
                }
            }
        }
        // 更新接口参数
        apiData.setParameters(list);
    }

    private static void responseHandler(JSONObject responsesJSONObject, JSONObject definitionsJSONObject, ApiData apiData) {

        // 响应码列表
        List<ApiResponseCode> codes = new ArrayList<>();
        for (String code : responsesJSONObject.keySet()) {

            // 响应码
            ApiResponseCode apiResponseCode = new ApiResponseCode();
            apiResponseCode.setCode(code);
            JSONObject codeJSONObject = responsesJSONObject.getJSONObject(code);
            apiResponseCode.setMsg(codeJSONObject.getString("description"));
            codes.add(apiResponseCode);

            // 响应数据
            if("200".equals(code)) {

                JSONObject schemaJSONObject = codeJSONObject.getJSONObject("schema");
                if(null != schemaJSONObject) {
                    // 响应数据逻辑
                    List<ApiParam> responses = new ArrayList<>();
                    String ref = schemaJSONObject.getString("$ref").replace("#/definitions/", "");
                    // 引用对象参数处理
                    List<ApiParam> params = refParamHandler(ref, definitionsJSONObject);
                    if(CollUtil.isNotEmpty(params)) {
                        boolean flag = true;
                        while (flag) {
                            responses.addAll(params);
                            flag = false;

                            List<ApiParam> itemParams = new ArrayList<>();
                            for (ApiParam param : params) {
                                if(StrUtil.isNotEmpty(param.getRef())) {
                                    itemParams.addAll(refParamHandler(param.getRef(), definitionsJSONObject));
                                }
                            }

                            if(itemParams.size() > 0) {
                                params = itemParams;
                                flag = true;
                            }
                        }
                    }
                    // 更新接口响应数据
                    apiData.setResponses(responses);
                }
            }
        }
        // 更新接口响应码
        apiData.setCodes(codes);
    }

    /**
     * 将引用对象，转化为apiParam列表
     * @param ref
     * @param definitionsJSONObject
     * @return
     */
    private static List<ApiParam> refParamHandler(String ref, JSONObject definitionsJSONObject) {

        JSONObject propertiesJSONObject = definitionsJSONObject.getJSONObject(ref).getJSONObject("properties");

        List<ApiParam> params = new ArrayList<>();
        for (String name : propertiesJSONObject.keySet()) {

            ApiParam apiParam = new ApiParam();
            apiParam.setName(name);
            apiParam.setType(propertiesJSONObject.getJSONObject(name).getString("type"));
            String description = propertiesJSONObject.getJSONObject(name).getString("description");
            apiParam.setDescription(description);

            JSONObject dataJSONObject = propertiesJSONObject.getJSONObject(name);
            if(null != dataJSONObject && "data".equals(name)) {
                String itemRef = dataJSONObject.getString("$ref");
                apiParam.setRef(itemRef);
                continue;
            }

            JSONObject rowsJSONObject = propertiesJSONObject.getJSONObject(name);
            if(null != rowsJSONObject && "rows".equals(name)) {
                JSONObject itemsJSONObject = rowsJSONObject.getJSONObject("items");
                String itemRef = itemsJSONObject.getString("$ref").replace("#/definitions/", "");
                apiParam.setRef(itemRef);
            }

            params.add(apiParam);

        }

        return params;
    }

    /**
     * 接口API分类处理，划归到制定tag下
     * @param tags
     * @param apiData
     */
    private static void tagsDataHandler(List<ApiTag> tags, ApiData apiData) {

        if (CollUtil.isNotEmpty(tags)) {
            for (ApiTag tag : tags) {
                if(apiData.getTag().equals(tag.getName())) {
                    tag.getApis().add(apiData);
                    return;
                }
            }
        }

        List<ApiData> apis = new ArrayList<>();
        apis.add(apiData);

        ApiTag apiTag = new ApiTag();
        apiTag.setApis(apis);
        apiTag.setName(apiData.getTag());

        tags.add(apiTag);
    }

}

注意：如果小伙们的接口返回数据结构跟本系统不一致，在解析接口响应数据时，要根据自己接口返回的数据结构去解析。

使用指南

  1. 去github上下载本系统的源码
  2. 初始化sql脚本
  3. 修改application.yml的数据库连接配置，并启动服务
  4. 保持系统启动状态，执行ApiDocumentGenerateTest.handler()方法

使用的freemarker 变量替换的语句：

  1. 接口文档基本信息
    ${data.title}
    ${data.date}
    ${data.version}
    ${data.notes}
  1. TAG基本信息
    <#list data.tags as tag>
        ${tag.name}
    </#list>
  1. 接口基本信息
    <#list tag.apis as api>
        ${api.name}
        ${api.path}
        ${api.type}
    </#list>
  1. 接口参数信息
    <#list api.parameters as param>
        ${param.name}
        ${param.type}
        ${param.requiredStr}
        ${param.description}
    </#list>
  1. 响应参数信息
    <#list api.responses as param>
        ${param.name}
        ${param.type}
        ${param.requiredStr}
        ${param.description}
    </#list>
  1. 响应码信息
    <#list api.code as item>
        ${item.code}
        ${item.msg}
    </#list>

一键生成的接口文档截图

在这里插入图片描述

一棵星
关注
  • 8
    点赞
  • 踩
  • 7
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
API接口模板-含Word和excel
08-06
接口文档标准的模板，包含两种word、excel模板，希望对大家有帮助
[技巧] 轻松快捷完成领导要求的word格式的接口文档，再也不用因为编写word格式的接口文档而烦恼
Gina61的博客
09-27 319
今天在开发完一个项目的接口之后，公司领导过来说：”需要一份word格式的接口文档，***本门主任需要看这些文档，记得接口文档做的好看一点“。然后领导拍拍我的肩膀转身就走了，身为一个资深后端，尤其是在外包公司，特别是给政府本门做外包的时候 。对于文档要求特别多，什么都需要文档说明。 我本人本身都不爱弄word这一块的接口文档，因为还要弄格式，每个接口参数、请求方式、响应都需要自己去一个一个粘贴，调格式特别麻烦。有时候一个项目功能负责点，接口特别多的时候。几百个接口需要弄两三天，比敲代码还累就很苦恼。就在想有没
如何快速生成接口文档（swagger和knife4j两种方式及其使用）
最新发布
m0_63144319的博客
05-14 1188
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发项目维护中或者项目人员更迭，方便后期人员查看、维护Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(它的主要作用是：使得前后端分离开发更加方便，有利于团队协作接口的文档在线自动生成，降低后端开发人员编写接口文档的负担。
关于接口文档
zuozuo的博客
02-13 467
其实对于接口文档，就是用来传递接口的信息，包括接口的数据传递，数据的请求，那么，文档的可读性就异常重要了。 当然word，txt，都可以用来写接口文档，只不过，对于word的各种格式，不见得所有程序猿都了然于胸，这个时候想让接口文档变得简洁美观，可读性优良的话，markdown就可以闪亮登场了。 下面记录一下，markdown的基本语法，因为编写markdown文件，很多编辑器都可以，比如ph...
接口自动化入门： swagger/word/ excel/ pdf等不同种类的接口文档理解！
04-01 855
最后，我们了解PDF文档。PDF文档是一种便携式文档格式，可以在不同平台和设备上进行阅读和分享。在接口自动化中，PDF文档通常用于保存和共享接口文档。我们可以将Swagger、Word或Excel文档转换为PDF格式，以便于团队成员和其他相关人员进行查阅和使用。总结起来，不同种类的接口文档都有各自的特点和用途。Swagger文档具有自动生成和可视化的特点，方便我们快速了解和测试API；Word文档灵活性强，适合个性化定制；Excel文档方便记录和管理接口信息；PDF文档便于共享和阅读。
后端接口文档例子 word
03-18
word版接口文档
微软word文档操作接口
u012091387的博客
07-20 767
word文档操作API
接口文档标准模板-含Word和excel两种
02-06
接口文档标准的模板，包含Word和excel两种模板。满足各种语言接口需要。
API接口模板word/Excel
09-03
API接口模板，word版本和Excel版本，用于平常的接口文档
接口模板.docx
09-03
1. 引言 1.1编写目的 本文是xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 文档的预期读者：  Xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 2 接口协议 2.1协议标准  数据传输采用HTTP/HTTPS 协议标准；  基于HTTP GET/POST方式进行数据请求；  字符编码格式统一为UTF-8；  所有字段名称大小写敏感；  请求头Content-Type：application/x-www-form-urlencoded； 2.2 接口地址 测试地址：http://url:port/gateway.do 正式地址：http://url:port/gateway.do
基于FME的一键批量生成word文档，用户只需要填好Excel表，工具便可自动生成标准化文档
06-28
本工具基于Excel表格信息实现标准化word文档的一键生成，支持在段落中插入文字、插入图片和在表格中插入文字。 对于不懂编程的人，只要弄清Excel表格的填写，便可以修改成适合自己工作场景的办公小助手，比如制作...
swagger 转 word 工具 Java代码，一键生成优美 word 格式 API 文档
02-23
4. **Word 文档生成**：最后，使用 Apache POI 将格式化后的数据写入 Word 文件，用户可以直接打开和打印，或者进一步编辑和定制。 在提供的 `swagger2word` 压缩包中，很可能包含了 Java 源代码、依赖库、示例 ...
基于Java的开源API接口文档管理系统设计源码
04-06
系统设计旨在为中小企业IT团队提供一个便捷、高效的API接口文档管理平台，通过在线填写文本框即可生成接口文档，支持文档的轻松管理和一键导出Word文档功能，方便在线和线下分享，有效提高了团队的工作效率。
数据库设计文档一键生成工具(支持多数据源).zip
06-08
本文将深入探讨“数据库设计文档一键生成工具”这一主题，它旨在简化数据库设计过程，提高工作效率。 首先，数据库设计文档是记录数据库结构、关系、逻辑和物理设计的详细文件，对于团队协作和项目维护至关重要。...
word一键生成三线表插件
11-28
配合提供的"一键实现Word文档三线表格制作方法说明文档.docx"，用户可以详细了解如何安装和使用这个插件。该文档可能包含了安装步骤、使用教程、快捷键设置以及常见问题解答等内容，确保用户能够顺利地将插件集成到...
根据word接口文档生成Java实体代码工具
迷失蒲公英
03-05 527
最近的工作涉及到针对接口文档来封装调用代码，文档中有些接口的请求报文或响应报文字段特别多，如果纯手工敲代码真的是一件很费劲的事情。基于这原因，考虑尽量减少枯燥的重复工作，直接实现了一个根据word接口文档生成Java实体代码工具。以上是根据word接口文档生成Java实体代码工具使用介绍，有需要的朋友可以用用，有什么疑问和需求也可以反馈给我。2.到在线工具点击“从word复制粘贴”，点击后会显示复制粘贴的内容。3.选择字段名列、字段类型列、字段长度列、字段备注列，4.设置备注字段组成。
knife4j---基于Swagger的文档优化
热门推荐
遇见1995
12-18 1万+
前言 knife4j 是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui. 为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j 更名后主要专注的方面 前后端Java代码以及前端Ui模块进行分离,...
自动化生成接口文档：详细教程及最佳实践
nhb687096的博客
01-05 1886
这些资料，对于【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴上万个测试工程师们走过最艰难的路程，希望也能帮助到你！
elsx一键生成word二次开发
09-29
elsx是一个功能强大的JavaScript库，可以用于读取、修改和生成Excel文档。它提供了一些方便的API和方法，使开发人员能够轻松地对Excel文件进行操作。elsx库还支持将Excel文件转换为其他格式，如CSV、HTML和JSON。 对于elsx一键生成Word二次开发，我推荐使用其他专门用于处理Word文档的库，如docxtemplater或officegen。这些库提供了一系列API和方法，可以帮助开发人员快速生成和修改Word文档。 在进行elsx一键生成Word的二次开发时，首先需要了解Word文档的结构和格式。然后，可以使用elsx库读取Excel文件的内容，并根据需要将其转换成Word文档的格式。例如，可以将Excel表格的每个单元格转换成Word文档中的表格和段落。 当然，在使用elsx库进行Excel到Word转换时，还需要处理一些细节，例如文本格式、样式和布局。这些细节可以使用其他库的功能来实现。可以使用docxtemplater库来指定Word模板，然后使用elsx库读取Excel文件的内容填充模板中的占位符。 总结起来，elsx库是一个优秀的用于Excel文件操作的库，但对于一键生成Word文档的二次开发，建议结合其他专门用于处理Word文档的库，以便更好地实现对Word文档的生成和修改。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值