API接口文档中将Swagger文档转Word 文档

一般的开发工作,尤其是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 requestList;   //请求体
    private List responseList;   //返回体
    private String requestParam;    //请求参数
    private String responseParam;   //回参数

//省略了getters and setters
}

 

 

 
   
public interface TableService {

    List tableList();
}
@Service
public class TableServiceImpl implements TableService {

    @Autowired
    private RestTemplate restTemplate;

    @Value("${swaggerUrl}")
    private String swaggerUrl;

    @Override
    public List
tableList() { String json = restTemplate.getForObject(swaggerUrl, String.class); Map 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>(){}); } catch (Exception e) { LoggerFactory.getLogger(WordService.class).error("parse error", e); } List
list = new LinkedList(); //得到host,并添加上http 或 https String host = StringUtils.substringBefore(swaggerUrl, ":") + String.valueOf(map.get("host")); //解析paths LinkedHashMap paths = (LinkedHashMap) map.get("paths"); if (paths != null) { Iterator> it = paths.entrySet().iterator(); while (it.hasNext()) { Table table = new Table(); List requestList = new LinkedList<>(); List 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 path = it.next(); url = path.getKey(); LinkedHashMap value = path.getValue(); Set requestTypes = value.keySet(); for (String str : requestTypes) { requestType += str + ","; } Iterator> it2 = value.entrySet().iterator(); // 不管有几种请求方式,都只解析第一种 Map.Entry firstRequestType = it2.next(); LinkedHashMap content = firstRequestType.getValue(); title = String.valueOf(((List) content.get("tags")).get(0)); description = String.valueOf(content.get("description")); List consumes = (List) content.get("consumes"); if (consumes != null && consumes.size() > 0) { for (String consume : consumes) { requestForm += consume + ","; } } List 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 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 responses = (LinkedHashMap) content.get("responses"); Iterator> it3 = responses.entrySet().iterator(); while (it3.hasNext()) { Response response = new Response(); Map.Entry entry = it3.next(); // 状态码 200 201 401 403 404 这样 String statusCode = entry.getKey(); LinkedHashMap 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 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 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 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 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 ParamMap(List list) { Map 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张图片

API接口文档中将Swagger文档转Word 文档_第2张图片

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

 API接口文档中将Swagger文档转Word 文档_第3张图片

 

转载于:https://www.cnblogs.com/qianjinyan/p/10823483.html

你可能感兴趣的:(API接口文档中将Swagger文档转Word 文档)