本文来源于：http://blog.csdn.net/guoxiaoqian8028/article/details/8565889

说明：

1、本缩写表是《编码命名规范》的附录。

2、本缩写表中列出的都是通用性缩写，不提供标准缩写，如：Win9x、COM 等。

3、使用本缩写表里的缩写时，请对其进行必要的注释说明。

4、除少数情况以外，大部分缩写与大小写无关。

通 用 缩 写 表

这是关于api基础写法的第三篇文章了，这里给下前两篇连接
《路径定义篇》 《参数接收篇》 ，对于本篇文章我们主要说下接口的数据返回值的问题。

格式选择

返回格式目前主流的应该只有XML、JSON两种吧，这里我们不做对比，我们使用JSON作为接口的返回格式。

数据返回格式

数据的返回格式其实是个比较纠结的问题，在restful风格中很多文章都讲解使用的是http状态码控制请求的结果状态，例如：http状态码为200~300的时候，为正常状态，response响应体即为所需要返回的数据，404时代表没有查询到数据，响应体即为空，500为系统错误，响应体也为空等等，但是这种方式也是存在很大问题的，一是http状态码是有限的，而且每个状态码都已经被赋予特殊的含义，在企业开发中当接口遇到错误的时候，我们可能更希望将结果状态码标记的更为详细，更利于前端开发者使用，毕竟写接口的目的也是方便前端使用，这样也可以降低前后端开发人员沟通成本。

下面给出我们在实际开发中使用的返回值统一格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

package com.zhuma.demo.comm.result;
import java.io.Serializable;
import com.zhuma.demo.comm.enums.ResultCode;

/**
 * Created by zhumaer on 17/5/24.
 */
 @Data
public class Result implements Serializable {

    private static final long serialVersionUID = -3948389268046368059L;

    private Integer code;

    private String msg;

    private Object data;

    public Result() {}

    public Result(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

    public static Result success() {
        Result result = new Result();
        result.setResultCode(ResultCode.SUCCESS);
        return result;
    }

    public static Result success(Object data) {
        Result result = new Result();
        result.setResultCode(ResultCode.SUCCESS);
        result.setData(data);
        return result;
    }

    public static Result failure(ResultCode resultCode) {
        Result result = new Result();
        result.setResultCode(resultCode);
        return result;
    }

    public static Result failure(ResultCode resultCode, Object data) {
        Result result = new Result();
        result.setResultCode(resultCode);
        result.setData(data);
        return result;
    }

    public void setResultCode(ResultCode code) {
        this.code = code.code();
        this.msg = code.message();
    }
}

备注

• 上面代码我们注意到其中引入了一个ResultCode枚举类，该类也是我们后面紧接着要说的，全局统一返回状态码。
• 这里说明下字段data不是在code=1为成功的时候才会有值哦，比如当code为参数无效错误时，data可以放入更详细的错误描述，用于指明具体是哪个参数为什么导致的无效的。

原文地址 : 如何快速制作出漂亮的截图

对于新媒体营销者来说，如果你服务的企业是互联网企业，或者说用户需要在通过电脑来购买或者使用你的服务，那么在文章中通过截图来指导，是一件非常常见的事情。

可能你经常看到公众号的文章中看到过，类似这样的手机演示截图：

或者是这样电脑端的浏览器截图：

可能你会想，做出这样的截图应该是挺复杂的吧？得先截图后，在找到浏览器或者 iPhone 手机的素材，然后再在 Photoshop 之类的软件中设计……

但反你认为麻烦的时候，你都应该要想一想：是不是有工具直接能一键完成。

顺着这个思路，我还是上了 Product Hunt – The best new products in tech.，利用「 Screenshot 」找到了Screely – Generate Beautiful Mockups，可以通过 Chrome 浏览器的方式，点击插件按钮，直接一键生成电脑端操作截图。

同样，对于移动端的截图，你可以使用 Mobile Mockup – Kapwing 一键生成手机端操作截图。

当然，如果你想要更高级的自定义移动端的设备类型，比如iPhone X 系列的「留海」等等，你可以同样搜索到非常多类似的工具，如果你有好的推荐，也欢迎你留言告诉我。

原文地址：Restful Api写法心得之二《参数接收篇》

原文作者：筑码-井哥

本篇文章主要说下接口的数据参数到底该如何接收，我们知道一个http请求最重要的意义就是将数据在服务器上进行传入与传出，本章主要讲的也就是传入。一次请求传递参数的方式主要有 URL路径中、请求头中、请求体中还有通过cookie等，下面我们分别对几种方式进行讲解。

MediaType的选择

MediaType即是Internet Media Type，互联网媒体类型；也叫做MIME类型，在Http协议消息头中，使用Content-Type来表示具体请求中的媒体类型信息。

• 对于POST、PUT、PATCH这种HTTP方法，统一使用 application/json，将参数放在请求体中以JSON格式传递至服务器
• 对于GET、DELETE的HTTP方法，使用默认类型（application/x-www-form-urlencoded）

★备注

特殊情况特殊考虑，例如进行文件上传时，使用 multipart/form-data类型等

路径参数

对应spring mvc框架中@PathVariable注解

★备注

这里有个注意的点，当路径参数值中有带点”.”的情况时，spring mvc框架中有对点做特殊处理，这导致在程序中只能接收到点之前的内容，例如你的请求是：GET https://api.zhuma.com/users/hehe.haha，后端在接收userId=’hehe.haha’时，只会接收到hehe字符串，后面的部分（.haha）被舍弃掉了。

解决方式是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package com.zhuma.demo.analyst.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration
public class MvcConfig extends WebMvcConfigurerAdapter {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUseSuffixPatternMatch(false);//可以让URL路径中带小数点 '.' 后面的值不被忽略 
    }

}

请求头参数

对应spring mvc框架中@RequestHeader注解

对于提供给APP（android、ios、pc） 的接口我们可能需要关注一些调用信息，例如 用户登录信息、调用来源、app版本号、api的版本号、安全验证信息 等等，我们将这些信息放入头信息（HTTP HEAD中），下面给出在参数命名的例子：

• X-Token 用户的登录token（用于兑换用户登录信息）
• Api-Version api的版本号
• App-Version app版本号
• Call-Source 调用来源(IOS、ANDROID、PC、WECHAT、WEB)
• Authorization 安全校验参数（后面会有文章详细介绍该如何做安全校验）
  这时你可能会思考一下几个问题：

1. 为什么需要收集 api版本号、app版本号、调用来源这些信息呢？
   这里解释下，主要有几个原因：

   ①. 方便线上环境定位问题，这也是一个重要的原因（我们后面会讲通过切面全局打印非GET请求的接口调用日志）。

   ②. 我们可以通过这些参数信息处理我们的业务逻辑，而没有必要在用到的时候我们才想起来让调用者将信息传递过来，导致同一功能性的参数，参数名和参数值不统一的情况发生。

2. 是每个接口都要这些参数么？
   是的，建议将所有的接口都传递上述参数信息。

3. 怎么做这些参数的校验呢？

   你可以写个拦截器，统一校验你的接口中全局的header参数，如果还是不太会写，可以参考这篇文章《统一参数校验》

原文地址 : Restful Api写法心得之一《路径定义篇》

原文链接：筑码-井哥

1. 前言

目前网站上已经有很多关于如何去写restful风格的api的文章，主要说明下我接下来写的关于api写法的连载文章的目的，一个是主要把自己在这方面的心得分享给大家，二是希望大家也能给出更好的意见、建议，欢迎在看文章后讨论。

本篇文章主要说下接口路径该怎么定义，一个URL地址的可读性对于调用者和维护者都是很重要的，当你规划好URL该怎么定义后，这也决定了java项目中你的controller类的划分，我们知道一个HTTP接口通常主要结构为： 协议://域名/应用content path/自定义路径?查询参数，例如：https://api.zhuma.com/zm-back/users?pageSize=10&pageNum=1 代表筑码网后台管理用户功能的API。

那我们到底该怎么定义我们的API URL会更好一些呢？下面给出几点建议。

2. 域名的利用

若域名无法区分出是api还是页面功能的时候，api路径后面统一加/api用于区分是接口服务。

1. https://back.zhuma.com/api/login

2. https://api-back.zhuma.com/login

上面举例中back代表着后台管理的意思，所以想要进入后台管理页面路径应该为：https://back.zhuma.com 前台当然要留给https://www.zhuma.com，在域名使用中我们可以利用三级域名对我们整体系统大的功能或应用进行很好的划分，正是因此，我们看到举例中路径上并没有加上应用的content path。

★ 备注

建议通过域名去区分api，也就是举例中2的方式

在开发中对于多环境开发我们也可以通过域名来区分，例如：

https://fe-api-back.zhuma.com 为联调环境，

https://qa-api-back.zhuma.com为QA测试环境，

https://stg-api-back.zhuma.com 为仿真环境，

https://api-back.zhuma.com 为生产环境等。

3. 词性使用

定义自定义路径部分时，使用名词的复数形式定义一个资源，如若有动词词性在url中考虑以下划线区分。

基本操作

GET /users # 获取用户列表

GET /users/{userId} # 查看某个具体的用户信息

POST /users # 新建一个用户

PUT /users/{userId} # 全量更新某一个用户信息

PATCH /users/{userId} # 选择性更新某一个用户信息

DELETE /users/{userId} # 删除某一个用户

批量操作

POST /users/_mget # 批量获取多个用户

POST /users/_mcreate # 批量创建多个用户

POST /users/_mupdate # 批量更新多个用户

POST /users/_mdelete # 批量删除多个用户

POST /users/_bulk # 批量功能组装（后面会讲到）

动词词性加入url（原则上此种情况是不被推荐的）

GET /users/_search # 搜索用户

POST /users/_init # 初化所有用户

来自：博客园（作者：tanwei81）

原文链接：

https://www.cnblogs.com/tanwei81/p/6814022.html

一、注解(annotations)列表

@SpringBootApplication：包含了@ComponentScan、@Configuration和@EnableAutoConfiguration注解。其中@ComponentScan让spring Boot扫描到Configuration类并把它加入到程序上下文。

@Configuration 等同于spring的XML配置文件；使用Java代码可以检查类型安全。

@EnableAutoConfiguration 自动配置。

@ComponentScan 组件扫描，可自动发现和装配一些Bean。

@Component可配合CommandLineRunner使用，在程序启动后执行一些基础任务。

@RestController注解是@Controller和@ResponseBody的合集,表示这是个控制器bean,并且是将函数的返回值直 接填入HTTP响应体中,是REST风格的控制器。

@Autowired自动导入。

@PathVariable获取参数。

@JsonBackReference解决嵌套外链问题。

@RepositoryRestResourcepublic配合spring-boot-starter-data-rest使用。

二、注解(annotations)详解

@SpringBootApplication：申明让spring boot自动给程序进行必要的配置，这个配置等同于：@Configuration ，@EnableAutoConfiguration 和 @ComponentScan 三个配置。

1
2
3
4
5
6
7
8
9
10

package com.example.myproject; 
import org.springframework.boot.SpringApplication; 
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication // same as @Configuration @EnableAutoConfiguration @ComponentScan 
public class Application { 
public static void main(String[] args) { 
SpringApplication.run(Application.class, args); 
} 
}

**@**ResponseBody：表示该方法的返回结果直接写入HTTP response body中，一般在异步获取数据时使用，用于构建RESTful的api。在使用@RequestMapping后，返回值通常解析为跳转路径，加上@responsebody后返回结果不会被解析为跳转路径，而是直接写入HTTP response body中。比如异步获取json数据，加上@responsebody后，会直接返回json数据。该注解一般会配合@RequestMapping一起使用。示例代码：

1
2
3
4
5

@RequestMapping(“/test”) 
@ResponseBody 
public String test(){ 
	return”ok”; 
}

@Controller：用于定义控制器类，在spring 项目中由控制器负责将用户发来的URL请求转发到对应的服务接口（service层），一般这个注解在类中，通常方法需要配合注解@RequestMapping。示例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13

@Controller 
@RequestMapping(“/demoInfo”) 
publicclass DemoController { 
  @Autowired 
  private DemoInfoService demoInfoService;
  @RequestMapping("/hello")
  public String hello(Map<String,Object> map){
    System.out.println("DemoController.hello()");
    map.put("hello","from TemplateController.helloHtml");
    //会使用hello.html或者hello.ftl模板进行渲染显示.
    return"/hello";
  }
}

@RestController：用于标注控制层组件(如struts中的action)，@ResponseBody和@Controller的合集。示例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package com.kfit.demo.web;

import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController;


@RestController 
@RequestMapping(“/demoInfo2”) 
publicclass DemoController2 {
  @RequestMapping("/test")
  public String test(){
  return"ok";
  }
}

@RequestMapping：提供路由信息，负责URL到Controller中的具体函数的映射。

@EnableAutoConfiguration：Spring Boot自动配置（auto-configuration）：尝试根据你添加的jar依赖自动配置你的Spring应用。例如，如果你的classpath下存在HSQLDB，并且你没有手动配置任何数据库连接beans，那么我们将自动配置一个内存型（in-memory）数据库”。你可以将@EnableAutoConfiguration或者@SpringBootApplication注解添加到一个@Configuration类上来选择自动配置。如果发现应用了你不想要的特定自动配置类，你可以使用@EnableAutoConfiguration注解的排除属性来禁用它们。

@ComponentScan：表示将该类自动发现扫描组件。个人理解相当于，如果扫描到有@Component、@Controller、@Service等这些注解的类，并注册为Bean，可以自动收集所有的Spring组件，包括@Configuration类。我们经常使用@ComponentScan注解搜索beans，并结合@Autowired注解导入。可以自动收集所有的Spring组件，包括@Configuration类。我们经常使用@ComponentScan注解搜索beans，并结合@Autowired注解导入。如果没有配置的话，Spring Boot会扫描启动类所在包下以及子包下的使用了@Service,@Repository等注解的类。

@Configuration：相当于传统的xml配置文件，如果有些第三方库需要用到xml文件，建议仍然通过@Configuration类作为项目的配置主类——可以使用@ImportResource注解加载xml配置文件。

@Import：用来导入其他配置类。

@ImportResource：用来加载xml配置文件。

@Autowired：自动导入依赖的bean

@Service：一般用于修饰service层的组件

@Repository：使用@Repository注解可以确保DAO或者repositories提供异常转译，这个注解修饰的DAO或者repositories类会被ComponetScan发现并配置，同时也不需要为它们提供XML配置项。

@Bean：用@Bean标注方法等价于XML中配置的bean。

@Value：注入Spring boot application.properties配置的属性的值。示例代码：

1
2

@Value(value = “#{message}”) 
private String message;

@Inject：等价于默认的@Autowired，只是没有required属性；

@Component：泛指组件，当组件不好归类的时候，我们可以使用这个注解进行标注。

@Bean:相当于XML中的,放在方法的上面，而不是类，意思是产生一个bean,并交给spring管理。

@AutoWired：自动导入依赖的bean。byType方式。把配置好的Bean拿来用，完成属性、方法的组装，它可以对类成员变量、方法及构造函数进行标注，完成自动装配的工作。当加上（required=false）时，就算找不到bean也不报错。

@Qualifier：当有多个同一类型的Bean时，可以用@Qualifier(“name”)来指定。与@Autowired配合使用。@Qualifier限定描述符除了能根据名字进行注入，但能进行更细粒度的控制如何选择候选者，具体使用方式如下：

1
2
3

@Autowired 
@Qualifier(value = “demoInfoService”) 
private DemoInfoService demoInfoService;

**@Resource(name=”name”,type=”type”)**：没有括号内内容的话，默认byName。与@Autowired干类似的事。

原文地址 docsify全接触

一直以来我都习惯直接用 markdown 写一些简单的项目文档，并且通过 git 同步到 Github 或者国内的码云上，以满足备份和查看的需求，但直到我遇到了 docsify ，在初步了解了一天后，我觉得这款工具或许可以代替我之前写文档的方式。

什么是 docsify

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html文件，所有转换工作都是在运行时进行。

官方的介绍其实就已经打动我了，因为 GitBook 和 Hexo ，一个有了解过，一个现在正在使用，它们的“特点”就是都需要编译，相对来说就会比较费时，而运行时编译就方便了很多，而且整个文档目录也不会被 .html 文件“污染”，虽然 SEO 会受到影响，但我不在乎！

开始使用

安装

官方推荐安装 docsify-cli 工具，可以方便创建及本地预览文档网站。

1

npm i docsify-cli -g

初始化

建议在项目的 ./docs 目录里写文档，可以通过下面的方式初始化项目：

1

docsify init ./docs

这里我也可以直接创建一个纯文档项目：

1

docsify init ./

本地预览

在上一步初始化完毕后，会看到 Initialization succeeded! Please run docsify serve ./ ，那我们接着执行 docsify serve ./ 就可以运行起一个支持实时预览的本地网站，通过 http://localhost:3000 可以访问。

1

docsify serve ./

基本操作

运行好后看到这样的页面就代表运行成功了，在开始写文档之前，先来了解一下初始化好后的这三个文件分别是做什么的。

• .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
• index.html 入口文件，也可以理解为项目配置文件
• README.md 文档默认主页

如何设计一个电商平台积分兑换系统？

公众号：狸猫技术窝

作者：原子弹大侠，高级技术专家

目录

1.拉开差距的一类面试题

2.业务需求描述

3.对业务流程的思考

4.物流配送进度查询，考虑到了吗？

5.事务的保证

6.消息中间件的引入

7.重试机制的引入

8.引入幂等性机制

9.对这类面试题的总结

1、拉开差距的一类面试题

现在面试经常会遇到一类问题，面试官让你现场设计出某个业务场景下的一个系统，这个系统往往在业务或者技术上有一定难度，主要考察的是你多年积淀下来的系统设计的能力以及技术思维的能力。

类似的这类系统设计题目很多，比如：

• 请你设计一个秒杀系统
• 请你设计一个支撑百万用户的IM消息系统
• 请你设计一个微信红包系统
• 请你设计一个电商平台积分兑换系统

这些题目本身都是开放式命题，没有固定答案。遇到这种问题，一定不要慌，关键是在现场要思路清楚，有理有据，慢慢分析。

本文就其中一个问题：设计一个电商平台的积分兑换系统，来详细阐述一下。文中会详细指出在系统设计的时候要考虑哪些要点，给大家展示出来这类问题思考的一个过程。

2、业务需求的描述

假设面试官现在给出来对于这个电商平台的积分兑换系统的相关需求如下：

1. 用户在电商平台里平时通过购买商品、晒单评论可以有不断的积累积分
2. 积累到足够的积分后，就可以在电商平台的积分兑换页面中，选择使用自己的积分来兑换一些礼品

需求其实就这么简单，那么面试官说了，针对这个业务场景给出你对这个机制实现的思考过程以及这里要注意的一些地方。

3、对业务流程的思考

如何思考？首先，用户不停的购买商品以及晒单评论，会不断的获取积分，那么是不是需要一张积分表，专门用来存储每个用户的积分呢？

没错，这个表是一定需要的，可以现场给出下述的表结构。

积分表：

• id（自增id主键）
• user_id（用户id）
• credit（积分）

继续来看，假设在积分兑换页面，用户选择用自己的20000积分兑换一瓶洗发水，后台的逻辑应该如何设计呢？

这个也是必须得现场给出一个思考过程的，这个其实看起来简单，但是很多年纪较轻，经验不足的朋友，可能没法快速思考出来。

首先你要用20000积分去进行兑换，那么一定是必须要在积分表里扣减掉这20000积分的吧？所以在流程设计中，首先就得有一个20000积分扣减的过程。

其次，你用这20000积分兑换了什么东西呢？

所以你是不是还需要一张单独的表，叫做积分兑换记录表，记录下来你这个用户本次用多少积分兑换了一件什么商品？

这个积分兑换记录表的结构如下所示，你是不是需要在下面的那个表里插入一条记录，说这个用户本次用多少积分兑换了哪个商品？

积分兑换表：

• id（自增id主键）
• user_id（用户id）
• exchanged_credit（用于兑换的积分）
• product_id（兑换的商品id）

最后，光是插入上述那条积分兑换记录是不够的，你必须得调用仓储业务模块的接口，通知仓储业务模块新增一条发货申请，而且应该是积分兑换对应的发货申请，这样保证仓库可以准备对应的商品进行发货。

这个发货申请大致对应如下的表结构：

发货申请表：

• id（自增id主键）
• type（发货类型，1：购买，2：积分兑换）
• credit_exchange_id（积分兑换表的id）
• product_id（要发货的商品id）

其实这里的发货申请表简化了很多，按理说还得有发货商品的数量等等字段，但是这里可以简化处理也没事，毕竟是面试现场。

简单画出来这个流程大致如下所示。

原文链接 使用Swagger2Markup实现导出API文档

原作者 飞狗

前言

在学会了如何使用Swagger之后，我们已经能够轻松地为Spring MVC或SpringBoot的Web项目自动构建出API文档了。但是，构建的文档必须通过在项目中整合swagger-ui、或使用单独部署的swagger-ui和/v2/api-docs返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上，再介绍一种生成静态API文档的方法，以便于构建更轻量部署和使用的API文档。 Swagger使用说明：REST API文档工具Swagger2，以及与SpringBoot的集成

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

项目主页：https://github.com/Swagger2Markup/swagger2markup

如何使用

在使用Swagger2Markup之前，我们先需要准备一个使用了Swagger的Web项目，REST API文档工具Swagger2，以及与SpringBoot的集成。

生成AsciiDoc

生成AsciiDoc的方式有两种：

1. 通过Java代码来生成

第一步：编辑pom.xml增加需要使用的相关依赖和仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>
<repositories>
    <repository>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

第二步：编写一个单元测试用例来生成执行生成文档的代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

/**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://127.0.0.1:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));
    }

    /**
     * 生成Markdown格式文档
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    }
    /**
     * 生成Confluence格式文档
     * @throws Exception
     */
    @Test
    public void generateConfluenceDocs() throws Exception {
        //    输出Confluence使用的格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/confluence/generated"));
    }

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        //    输出Ascii到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
    }

以上代码内容很简单，大致说明几个关键内容：

• MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP
• from(new URL("http://localhost:8080/v2/api-docs")：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
• toFolder(Paths.get("src/docs/asciidoc/generated")：指定最终生成文件的具体目录位置 输出到单个文件