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<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请求中的字段，如果要逐个手动，真心好类

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