一般的开发工作,尤其是API接口的开发工作,首先要有开发文档,接口说明文档

ok,后来开发完毕了

和页面联调,或者是和第三方联调的时候,

这个时候,SA systeam admin 就会开始直接让开发改代码了,比如增加一个入参,入参名进行一些变化,比如比天性进行变化,比如字符串类型修改最大长度,etc.

你会说,不行啊,要走变更流程啊,先更新接口说明文档啊

这个时候,就不是现有鸡蛋后有鸡的模式了

变成了先有鸡之后进行下蛋的模式

http://www.cnblogs.com/jmcui/p/8298823.htm

Swagger文档转Word 文档

原文地址链接如上,springmvc 开发,创建了三个对象, 对swagger的json文件进行解析和拼接,成为API文档

可以自己有空的时候试一下,用springboot,然后页面用thymeleaf取出拼接成word格式

主要实现思想

添加一个Request对象,捕获请求的一些信息

public class Request {

    private String name;   //参数名
private String type; //数据类型
private String paramType; //参数类型 path,
private Boolean require; //是否必填
private String remark; //说明 //省略了getters and setters
}

添加一个Response对象,捕获返回体中的一些信息

public class Response {

    private String description;   //返回参数
private String name; //参数名
private String remark; //说明 public Response(){ } public Response(String description, String name, String remark) {
this.description = description;
this.name = name;
this.remark = remark;
} //省略了getters and setters
}

Table是用来解析Json,捕获Json中的请求和返回体,接收一些接口描述信息

public class Table {

    private String title;    //大标题
private String tag; //小标题
private String url; //url
private String description; //描述
private String requestForm; //请求参数格式
private String responseForm; //响应参数格式
private String requestType; //请求方式
private List<Request> requestList; //请求体
private List<Response> responseList; //返回体
private String requestParam; //请求参数
private String responseParam; //回参数 //省略了getters and setters
}

public interface TableService {

    List<Table> tableList();
}
@Service
public class TableServiceImpl implements TableService { @Autowired
private RestTemplate restTemplate; @Value("${swaggerUrl}")
private String swaggerUrl; @Override
public List<Table> tableList() {
String json = restTemplate.getForObject(swaggerUrl, String.class); Map<String, Object> map = new HashMap<>();
ObjectMapper mapper = new ObjectMapper();
mapper.configure(JsonParser.Feature.ALLOW_UNQUOTED_FIELD_NAMES, true);
mapper.configure(JsonParser.Feature.ALLOW_UNQUOTED_CONTROL_CHARS, true);
mapper.configure(JsonParser.Feature.ALLOW_SINGLE_QUOTES, true); try {
// convert JSON string to Map
map = mapper.readValue(json, new TypeReference<HashMap<String,Object>>(){});
} catch (Exception e) {
LoggerFactory.getLogger(WordService.class).error("parse error", e);
} List<Table> list = new LinkedList();
//得到host,并添加上http 或 https
String host = StringUtils.substringBefore(swaggerUrl, ":") + String.valueOf(map.get("host"));
//解析paths
LinkedHashMap<String, LinkedHashMap> paths = (LinkedHashMap) map.get("paths");
if (paths != null) {
Iterator<Map.Entry<String, LinkedHashMap>> it = paths.entrySet().iterator();
while (it.hasNext()) {
Table table = new Table();
List<Request> requestList = new LinkedList<>();
List<Response> responseList = new LinkedList<>();
// 请求参数格式,类似于 multipart/form-data
String requestForm = "";
// 请求参数格式,类似于 multipart/form-data
String responseForm = "";
// 请求方式,类似为 get,post,delete,put 这样
String requestType = "";
String url; // 请求路径
String title; // 大标题(类说明)
String tag; // 小标题 (方法说明)
String description; //接口描述 Map.Entry<String, LinkedHashMap> path = it.next();
url = path.getKey(); LinkedHashMap<String, LinkedHashMap> value = path.getValue();
Set<String> requestTypes = value.keySet();
for (String str : requestTypes) {
requestType += str + ",";
} Iterator<Map.Entry<String, LinkedHashMap>> it2 = value.entrySet().iterator();
// 不管有几种请求方式,都只解析第一种
Map.Entry<String, LinkedHashMap> firstRequestType = it2.next();
LinkedHashMap content = firstRequestType.getValue();
title = String.valueOf(((List) content.get("tags")).get(0));
description = String.valueOf(content.get("description"));
List<String> consumes = (List) content.get("consumes");
if (consumes != null && consumes.size() > 0) {
for (String consume : consumes) {
requestForm += consume + ",";
}
}
List<String> produces = (List) content.get("produces");
if (produces != null && produces.size() > 0) {
for (String produce : produces) {
responseForm += produce + ",";
}
} tag = String.valueOf(content.get("summary"));
//请求体
List parameters = (ArrayList) content.get("parameters");
if (parameters != null && parameters.size() > 0) {
for (int i = 0; i < parameters.size(); i++) {
Request request = new Request();
LinkedHashMap<String, Object> param = (LinkedHashMap) parameters.get(i);
request.setName(String.valueOf(param.get("name")));
request.setType(param.get("type") == null ? "Object" : param.get("type").toString());
request.setParamType(String.valueOf(param.get("in")));
request.setRequire((Boolean) param.get("required"));
request.setRemark(String.valueOf(param.get("description")));
requestList.add(request);
}
}
//返回体
LinkedHashMap<String, Object> responses = (LinkedHashMap) content.get("responses");
Iterator<Map.Entry<String, Object>> it3 = responses.entrySet().iterator();
while (it3.hasNext()) {
Response response = new Response();
Map.Entry<String, Object> entry = it3.next();
// 状态码 200 201 401 403 404 这样
String statusCode = entry.getKey();
LinkedHashMap<String, Object> statusCodeInfo = (LinkedHashMap) entry.getValue();
String statusDescription = (String) statusCodeInfo.get("description");
response.setName(statusCode);
response.setDescription(statusDescription);
response.setRemark(null);
responseList.add(response);
} // 模拟一次HTTP请求,封装请求体和返回体
// 得到请求方式
String restType = firstRequestType.getKey();
Map<String, Object> paramMap = ParamMap(requestList);
String buildUrl = buildUrl(host + url, requestList); //封装Table
table.setTitle(title);
table.setUrl(url);
table.setTag(tag);
table.setDescription(description);
table.setRequestForm(StringUtils.removeEnd(requestForm, ","));
table.setResponseForm(StringUtils.removeEnd(responseForm, ","));
table.setRequestType(StringUtils.removeEnd(requestType, ","));
table.setRequestList(requestList);
table.setResponseList(responseList);
table.setRequestParam(String.valueOf(paramMap));
table.setResponseParam(doRestRequest(restType, buildUrl, paramMap));
list.add(table);
}
}
System.out.println("===============================");
System.out.println(list);
return list; } /**
* 重新构建url
*
* @param url
* @param requestList
* @return etc:http://localhost:8080/rest/delete?uuid={uuid}
*/
private String buildUrl(String url, List<Request> requestList) {
String param = "";
if (requestList != null && requestList.size() > 0) {
for (Request request : requestList) {
String name = request.getName();
param += name + "={" + name + "}&";
}
}
if (StringUtils.isNotEmpty(param)) {
url += "?" + StringUtils.removeEnd(param, "&");
}
return url; } /**
* 发送一个 Restful 请求
*
* @param restType "get", "head", "post", "put", "delete", "options", "patch"
* @param url 资源地址
* @param paramMap 参数
* @return
*/
private String doRestRequest(String restType, String url, Map<String, Object> paramMap) {
Object object = null;
try {
switch (restType) {
case "get":
object = restTemplate.getForObject(url, Object.class, paramMap);
break;
case "post":
object = restTemplate.postForObject(url, null, Object.class, paramMap);
break;
case "put":
restTemplate.put(url, null, paramMap);
break;
case "head":
HttpHeaders httpHeaders = restTemplate.headForHeaders(url, paramMap);
return String.valueOf(httpHeaders);
case "delete":
restTemplate.delete(url, paramMap);
break;
case "options":
Set<HttpMethod> httpMethods = restTemplate.optionsForAllow(url, paramMap);
return String.valueOf(httpMethods);
case "patch":
object = restTemplate.execute(url, HttpMethod.PATCH, null, null, paramMap);
break;
case "trace":
object = restTemplate.execute(url, HttpMethod.TRACE, null, null, paramMap);
break;
default:
break;
}
} catch (Exception ex) {
// 无法使用 restTemplate 发送的请求,返回""
// ex.printStackTrace();
return "";
}
return String.valueOf(object);
} /**
* 封装post请求体
*
* @param list
* @return
*/
private Map<String, Object> ParamMap(List<Request> list) {
Map<String, Object> map = new HashMap<>(8);
if (list != null && list.size() > 0) {
for (Request request : list) {
String name = request.getName();
String type = request.getType();
switch (type) {
case "string":
map.put(name, "string");
break;
case "integer":
map.put(name, 0);
break;
case "number":
map.put(name, 0.0);
break;
case "boolean":
map.put(name, true);
default:
map.put(name, null);
break;
}
}
}
return map;
}
}

可以是我用swagger的时候,对入参描述的不准,目前我还不能捕获到一个对象,比如json请求中的字段,如果要逐个手动,真心好类

而作者提供的截图中,返回参数是一个一个字段,罗列地很清楚

API接口文档中将Swagger文档转Word 文档的更多相关文章

  1. 利用POI操作不同版本号word文档中的图片以及创建word文档

    我们都知道要想利用java对office操作最经常使用的技术就应该是POI了,在这里本人就不多说到底POI是什么和怎么用了. 先说本人遇到的问题,不同于利用POI去向word文档以及excel文档去写 ...

  2. Android根据word模板文档将表单数据生成word文档的方案整理

    版权声明:本文为HaiyuKing原创文章,转载请注明出处! 前言 尝试的方案包括以下几种: freemarker 只能在java项目上运行,无法在Android项目上运行: 参考资料:<Fre ...

  3. 在项目中利用TX Text Control进行WORD文档的编辑显示处理

    在很多文档管理的功能模块里面,我们往往需要对WORD稳定进行展示.编辑等处理,而如果使用微软word控件进行处理,需要安装WORD组件,而且接口使用也不见得简单易用,因此如果有第三方且不用安装Offi ...

  4. c#中操作word文档-四、对象模型

    转自:http://blog.csdn.net/ruby97/article/details/7406806 Word对象模型  (.Net Perspective) 本文主要针对在Visual St ...

  5. c# word文档的操作

    参考https://blog.csdn.net/ruby97/article/details/7406806 Word对象模型  (.Net Perspective) 本文主要针对在Visual St ...

  6. 使用python编辑和读取word文档

    python调用word接口主要用到的模板为python-docx,基本操作官方文档有说明. python-docx官方文档地址 使用python新建一个word文档,操作就像文档里介绍的那样: fr ...

  7. [java,2017-05-04] 创建word文档

    package test; import java.text.SimpleDateFormat; import java.util.Date; import com.aspose.words.Data ...

  8. asp.net 将word文档进行编辑并导出一个新的word

    最近做项目,需要多word文档进行编辑并导出一个新的word,在最初的word编辑中留下特定的字符串用来替换,然后在本地生成一个新的word文档,并且不修改服务器中的word文档,这样才能保证服务器中 ...

  9. ABBYY将JPEG文件转换成Word文档的方法

    日常工作中处理JPEG格式的图像文件时,有时需要转换成Word文档进行编辑,市场上应用而生了很多转换工具,相信不少人听说过OCR(光学字符识别)软件,可以用来转换图像文件,而在OCR软件中, ABBY ...

随机推荐

  1. 【linux基础】Ubuntu下的终端多标签切换快捷键

    method: 方法一: alt+ alt+ alt+ 方法二: ctrl + pageUp ctrl + pageDown 方法三: Edit--> Keybord Shortcuts 到这里 ...

  2. npm镜像指定用淘宝镜像去下载

    使用npm下载,蜗牛,使用cnpm又觉得那啥,所以.把cnpm也就是淘宝镜像绑定成npm下载的代理,这样使用npm的时候其实是用淘宝镜像去下载,这感觉,good! 1. npm config set ...

  3. 关于async await的测试

    async await的教程:https://www.cnblogs.com/zhaoshujie/p/11192036.html 异步方法: private async Task<string ...

  4. CF1210A Anadi and Domino

    思路: 很有意思的思维题. 实现: #include <bits/stdc++.h> using namespace std; int check(vector<int>&am ...

  5. redis 启动配置文件加载报错 service redis does not support chkconfig

    # chkconfig: # description:Redis is a persistent key-value database 网上资料 上面的注释的意思是,redis服务必须在运行级2,3, ...

  6. NoSQL数据库一Redis基本使用

    基本操作 参考教程:https://www.yiibai.com/redis/Redis 是 Key-Value 内存数据库,操作是通过各种指令进行的,比如 SET 指令可以设置键值对,而 GET 指 ...

  7. c语言 c++程序运行过程

    我们写好的  .c  .cpp   文件在计算机中如何运行. 一个.c 文件  .cpp  文件  首先经过 预编译形成  . i 文件  在这个过程中 主要处理程序中的#  以及进行宏替换 然后编译 ...

  8. spring cloud微服务实践一

    最近在学习spring框架.其中spring cloud在微服务方面很火,所以在学习过程中,也做一些记录. 注:这一个系列的开发环境版本为 java1.8, spring boot2.x, sprin ...

  9. element-ui 合并单元格的方法

    arraySpanMethod({ row, column, rowIndex, columnIndex }) { // 只合并区域位置          //columnIndex 横的第一列    ...

  10. (六)springmvc之ModelAndView、Model、Map、ModelMap

    <a href="<%=request.getContextPath()%>/responseData/response_1">使用原生的作用域</a ...