Springboot2.x，测试 自定义属性 List Map 属性绑定对象 多环境支持 加密解密 jasypt swagger2 自动校验 静态文档swagger2Markup

1. 简单介绍

pom

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.3.RELEASE</version>
		<relativePath/>
	</parent>
    
    <!-- groupId、artifactId、version、name、description -->
	<groupId>com.didispace</groupId>
	<artifactId>chapter1-1</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>chapter1-1</name>
	<description>快速入门</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
        
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
        
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

controller

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String index() {
        return "Hello World";
    }

}

测试

src/main/java包下：com.didispace.chapter21 的类 Chapter21Application

src/test/java包下：com.didispace.chapter21 的类 Chapter21ApplicationTests

@RunWith(SpringRunner.class) //此注解，会运行整个程序
@SpringBootTest //这两个注解，缺一不可
public class Chapter11ApplicationTests {

    @Autowired
    private HelloController helloController;

    @Test
    public void getHello() throws Exception {
        helloController.index();
    }

}

 private MockMvc mvc;

    @Before
    public void setUp() throws Exception {
        //构建 mock
        mvc = MockMvcBuilders.standaloneSetup(new HelloController()).build();
    }

    @Test
    public void getHello() throws Exception {
 //提交 请求，接收返回为json，200
        mvc.perform(MockMvcRequestBuilders.get("/hello").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(content().string(equalTo("Hello World")));
    }

accept 
英 /əkˈsept/  美 /əkˈsept/  全球(英国)  
简明 牛津 新牛津  韦氏  柯林斯 例句  百科
v. 接受，收受；同意，赞成；相信，认为……正确；忍受，容忍；吸纳，招收；接纳；承担（责任等），承认；承兑，认付（单据等）；不排斥；适配

yaml

• 使用test环境，8882端口 启动

server:
  port: 8881
spring:
  profiles:
    active: test
---
spring:
  profiles: test
server:
  port: 8882
---
spring:
  profiles: prod
server:
  port: 8883

application-dev.properties
application-test.properties
application-prod.properties

2. 自定义属性配置

最基本的读取 $

• 原因是， Spring Boot 是以 iso-8859 的编码⽅式读取 application.properties 配置⽂件。

book.name=SpringCloudInAction
book.author=ZhaiYongchao
book.desc=${book.author}  is writing《${book.name}》 #用yaml不会乱码

@Component
public class Book {

    @Value("${book.name}")
    private String name;
    @Value("${book.author}")
    private String author;

    // 省略getter和setter
}

@Value注解加载属性值的时候可以支持两种表达式来进行配置：

• 一种是我们上面介绍的PlaceHolder方式，格式为 ${...}，大括号内为PlaceHolder
• 另外还可以使用SpEL表达式（Spring Expression Language）， 格式为 #{...}，大括号内为SpEL表达式
  • 这种方法 不行

使用随机数

# 随机字符串 8120cc2892074a9d67d43a91bb0bc830
blog.value=${random.value}

# 随机int
blog.number=${random.int}

# 随机long 
blog.bignumber=${random.long}

# 10以内的随机数。最大为9
blog.test1=${random.int(10)}

# 10-20的随机数
blog.test2=${random.int[10,20]}

运行时 设置

java -jar xxx.jar --server.port=8888

java -jar xxx.jar --spring.profiles.active=test
java -jar -Dspring.profiles.active=prod 1.jar

# 设置后就能屏蔽，运行时设置参数： SpringApplication.setAddCommandLineProperties(false)

属性加载顺序

Spring Boot为了能够更合理的重写各属性的值，使用了下面这种较为特别的属性加载顺序：

1. 命令行中传入的参数。
2. SPRING_APPLICATION_JSON中的属性。SPRING_APPLICATION_JSON是以JSON格式配置在系统环境变量中的内容。
3. java:comp/env中的JNDI属性。
4. Java的系统属性，可以通过System.getProperties()获得的内容。
5. 操作系统的环境变量
6. 通过random.*配置的随机属性
7. 位于当前应用jar包之外，针对不同{profile}环境的配置文件内容，例如：application-{profile}.properties或是YAML定义的配置文件
8. 位于当前应用jar包之内，针对不同{profile}环境的配置文件内容，例如：application-{profile}.properties或是YAML定义的配置文件
9. 位于当前应用jar包之外的application.properties和YAML配置内容
10. 位于当前应用jar包之内的application.properties和YAML配置内容
11. 在@Configuration注解修改的类中，通过@PropertySource注解定义的属性
12. 应用默认属性，使用SpringApplication.setDefaultProperties定义的内容

优先级按上面的顺序有高到低，数字越小优先级越高。

可以看到，其中第7项和第9项都是从应用jar包之外读取配置文件，所以，实现外部化配置的原理就是从此切入，为其指定外部配置文件的加载位置来取代jar包之内的配置内容。通过这样的实现，我们的工程在配置中就变的非常干净，我们只需要在本地放置开发需要的配置即可，而其他环境的配置就可以不用关心，由其对应环境的负责人去维护即可。

2.x 新特性

在Spring Boot 2.0中推出了Relaxed Binding 2.0，对原有的属性绑定功能做了非常多的改进以帮助我们更容易的在Spring应用中加载和读取配置信息。下面本文就来说说Spring Boot 2.0中对配置的改进。

配置文件绑定

简单类型

• 只有 1 2 是等价的。1会报提示错误。最好使用2，配置读取都用2
• 配置的2，用3 不能读取。反之配置3，用2可以读取。
• 4和其他完全不等价

在Spring Boot 2.0中对配置属性加载的时候会除了像1.x版本时候那样移除特殊字符外，还会将配置均以全小写的方式进行匹配和加载。所以，下面的4种配置方式都是等价的：

• properties格式：

spring.jpa.databaseplatform=mysql #全小写
spring.jpa.database-platform=mysql #全小写，单词加 -
spring.jpa.databasePlatform=mysql #多个单词 驼峰命名
spring.JPA.database_platform=mysql # 缩写单词大写。 下划线 分隔多个单词

• yaml格式：

spring:
  jpa:
    databaseplatform: mysql
    database-platform: mysql
    databasePlatform: mysql
    database_platform: mysql
 
spring:
  jpa:
    database-platform:  默认配置和使用，都使用此配置。

Tips：推荐使用全小写配合-分隔符的方式来配置，比如：spring.jpa.database-platform=mysql

List类型

在properties文件中使用[]来定位列表类型，比如：

spring.my-example.url[0]=http://example.com
spring.my-example.url[1]=http://spring.io

也支持使用逗号分割的配置方式，上面与下面的配置是等价的：

spring.my-example.url=http://example.com,http://spring.io

而在yaml文件中使用可以使用如下配置：

spring:
  my-example:
    url:
      - http://example.com
      - http://spring.io

也支持逗号分割的方式：

spring:
  my-example:
    url: http://example.com, http://spring.io

注意：在Spring Boot 2.0中对于List类型的配置必须是连续的，不然会抛出UnboundConfigurationPropertiesException异常，所以如下配置是不允许的：

foo[0]=a
foo[2]=b

在Spring Boot 1.x中上述配置是可以的，foo[1]由于没有配置，它的值会是null

Map类型

Map类型在properties和yaml中的标准配置方式如下：

• properties格式：

spring.my-example.foo=bar
spring.my-example.hello=world

• yaml格式：

spring:
  my-example:
    foo: bar
    hello: world

注意：如果Map类型的key包含非字母数字和-的字符，需要用[]括起来，比如：

spring:
  my-example:
    '[foo.baz]': bar

环境属性绑定

简单类型

在环境变量中通过小写转换与.替换_来映射配置文件中的内容，比如：环境变量SPRING_JPA_DATABASEPLATFORM=mysql的配置会产生与在配置文件中设置spring.jpa.databaseplatform=mysql一样的效果。

• 测试失败，不行，但大小写 可以转换

List类型

由于环境变量中无法使用[和]符号，所以使用_来替代。任何由下划线包围的数字都会被认为是[]的数组形式。比如：

MY_FOO_1_ = my.foo[1]
MY_FOO_1_BAR = my.foo[1].bar
MY_FOO_1_2_ = my.foo[1][2]

另外，最后环境变量最后是以数字和下划线结尾的话，最后的下划线可以省略，比如上面例子中的第一条和第三条等价于下面的配置：

MY_FOO_1 = my.foo[1]
MY_FOO_1_2 = my.foo[1][2]

系统属性绑定

简单类型

系统属性与文件配置中的类似，都以移除特殊字符并转化小写后实现绑定，比如下面的命令行参数都会实现配置spring.jpa.databaseplatform=mysql的效果：

-Dspring.jpa.database-platform=mysql
-Dspring.jpa.databasePlatform=mysql
-Dspring.JPA.database_platform=mysql  #除了这个，其他都行。用databaseplatform，兼容3个。

List类型

系统属性的绑定也与文件属性的绑定类似，通过[]来标示，比如：

系统属性的绑定也与文件属性的绑定类似，通过[]来标示，比如：

-D"spring.my-example.url[0]=http://example.com"
-D"spring.my-example.url[1]=http://spring.io"

同样的，他也支持逗号分割的方式，比如：

-Dspring.my-example.url=http://example.com,http://spring.io

属性的读取

上文介绍了Spring Boot 2.0中对属性绑定的内容，可以看到对于一个属性我们可以有多种不同的表达，但是如果我们要在Spring应用程序的environment中读取属性的时候，每个属性的唯一名称符合如下规则：

• 通过.分离各个元素
• 最后一个.将前缀与属性名称分开
• 必须是字母（a-z）和数字(0-9)
• 必须是小写字母
• 用连字符-来分隔单词
• 唯一允许的其他字符是[和]，用于List的索引
• 不能以数字开头

所以，如果我们要读取配置文件中spring.jpa.database-platform的配置，可以这样写：

this.environment.containsProperty("spring.jpa.database-platform")

而下面的方式是无法获取到spring.jpa.database-platform配置内容的：

• 说的 很正确。配置 database-platform，用 databasePlatform 无法读取。
• 若反过来。配置：databasePlatform，用database-platform，可以读取。

this.environment.containsProperty("spring.jpa.databasePlatform")

注意：使用@Value获取配置内容的时候也需要这样的特点

ConfigurationProperties

在Spring Boot 2.0中增加了新的绑定API来帮助我们更容易的获取配置信息。下面举个例子来帮助大家更容易的理解：

例子一：简单类型

假设在propertes配置中有这样一个配置：com.didispace.foo=bar

我们为它创建对应的配置类：

@Data
//@Component 应该需要加 。
@ConfigurationProperties(prefix = "com.didispace")
public class FooProperties {

    private String foo;

}

@EnableConfigurationProperties({MyModel.class}) //或者主类加此 注解

接下来，通过最新的Binder就可以这样来拿配置信息了：

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        ApplicationContext context = SpringApplication.run(Application.class, args);

        Binder binder = Binder.get(context.getEnvironment());

        // 绑定简单配置
        FooProperties foo = binder.bind("com.didispace", Bindable.of(FooProperties.class)).get();
        System.out.println(foo.getFoo());
    }
}
//@Component 直接把 配置类，交给spring，注入即可。

例子二：List类型

如果配置内容是List类型呢？比如：

com.didispace.post[0]=Why Spring Boot
com.didispace.post[1]=Why Spring Cloud //上文件增加：    private List<String> post; 读取

com.didispace.posts[0].title=Why Spring Boot
com.didispace.posts[0].content=It is perfect!
com.didispace.posts[1].title=Why Spring Cloud
com.didispace.posts[1].content=It is perfect too!

要获取这些配置依然很简单，可以这样实现：

ApplicationContext context = SpringApplication.run(Application.class, args);

Binder binder = Binder.get(context.getEnvironment());

// 绑定List配置
List<String> post = binder.bind("com.didispace.post", Bindable.listOf(String.class)).get();
System.out.println(post);

List<PostInfo> posts = binder.bind("com.didispace.posts", Bindable.listOf(PostInfo.class)).get();
System.out.println(posts);

本系列教程《Spring Boot 2.x基础教程》点击直达！。

3. boot 2.4 对 多环境配置的支持更改

on-profile

spring:
  profiles: "dev"

name: dev.didispace.com

---

spring:
  profiles: "test"

name: test.didispace.com

2.4版本之后

而在本次2.4版本升级之后，我们需要将spring.profiles配置用spring.config.activate.on-profile替代，比如上面的配置需要修改为如下配置：

spring:
  config:
    activate:
      on-profile: "dev"

name: dev.didispace.com

---

spring:
  config:
    activate:
      on-profile: "test"

name: test.didispace.com

指定环境启动

应用启动的时候，我们要加载不同的环境配置的参数不变，依然采用spring.profiles.active参数

java -jar myapp.jar -Dspring.profiles.active=dev

默认使用某一个环境的配置 未变

spring:
  profiles:
    active: "dev"

---

spring:
  config:
    activate:
      on-profile: "dev"

name: dev.didispace.com

2.4之前的分组配置

spring:
  profiles:
    active: "dev"

---
spring.profiles: "dev"
spring.profiles.include: "dev-db,dev-mq"

---
spring.profiles: "dev-db"

db: dev-db.didispace.com

---
spring.profiles: "dev-mq"

mq: dev-mq.didispace.com

2.4的分组配置

spring:
  profiles:
    active: "dev"
    group:
      "dev": "dev-db,dev-mq"
      "prod": "prod-db,prod-mq"

---
spring:
  config:
    activate:
      on-profile: "dev-db"

db: dev-db.didispace.com

---
spring:
  config:
    activate:
      on-profile: "dev-mq"

mq: dev-mq.didispace.com


=====================================
---
spring:
  config:
    activate:
      on-profile: "prod-db"

db: prod-db.didispace.com

---
spring:
  config:
    activate:
      on-profile: "prod-mq"

mq: prod-mq.didispace.com

        @Value("${db}")//: ，多了个：号，也行
        private String db;

啥是 原数据

D:\MyFile\softdata\maven\org\springframework\boot\spring-boot\2.4.1\
spring-boot-2.4.1.jar!\META-INF\
additional-spring-configuration-metadata.json

{
  "groups": [
    {
      "name": "logging",
      "type": "org.springframework.boot.context.logging.LoggingApplicationListener"
    }
  ],
  "properties": [
    {
      "name": "debug",
      "type": "java.lang.Boolean",
      "description": "Enable debug logs.",
      "sourceType": "org.springframework.boot.context.logging.LoggingApplicationListener",
      "defaultValue": false
    }
    ]
}

• 这些就是我们常用的Spring Boot原生配置的元数据信息。

• 它可以帮助IDE来完成配置联想和配置提示的展示。

• 而我们自定义配置之所以会报警告，同时也没有提示信息，就是因为没有这个元数据的配置文件！

配置元数据的自动生成

第一步：创建一个配置类，定义一个自定义配置

@Data
@Configuration
@ConfigurationProperties(prefix = "com.didispace")
public class DidiProperties {
    
    /**
     * 这是一个测试配置
     */
    private String from;

}

第二步：在pom.xml中添加自动生成配置元数据的依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
</dependency>

第三步：mvn install下这个项目。

此时我们可以在工程target目录下找到元数据文件：

同时，我们在配置文件中尝试编写这个自定义的配置项时，可以看到编译器给出了联想和提示：

//提示：这是一个测试配置
com.didispace.from=dfdf

4. 分布式配置中心（加密解密）

Spring Cloud Config提供了对属性进行加密解密的功能，

spring.datasource.username=didi
spring.datasource.password={cipher}dba6505baa

使用{cipher}前缀来标注该内容是一个加密值，当微服务客户端来加载配置时，配置中心会自动的为带有{cipher}前缀的值进行解密。

使用前提

在使用Spring Cloud Config的加密解密功能时，

为了启用该功能，我们需要在配置中心的运行环境中安装不限长度的JCE版本（Unlimited Strength Java Cryptography Extension）。

• 虽然，JCE功能在JRE中自带，但是默认使用的是有长度限制的版本。
• 我们可以从Oracle的官方网站中下载到它，它是一个压缩包，解压后可以看到下面三个文件：

README.txt
local_policy.jar
US_export_policy.jar

将local_policy.jar和US_export_policy.jar两个文件复制到$JAVA_HOME/jre/lib/security目录下，覆盖原来的默认内容。到这里，加密解密的准备工作就完成了。

相关端点

在完成了JCE的安装后，可以尝试启动配置中心。在控制台中，将会输出了一些配置中心特有的端点，主要包括：

• /encrypt/status：查看加密功能状态的端点
• /key：查看密钥的端点
• /encrypt：对请求的body内容进行加密的端点
• /decrypt：对请求的body内容进行解密的端点

可以尝试通过GET请求访问/encrypt/status端点，我们将得到如下内容：

{
  "description": "No key was installed for encryption service",
  "status": "NO_KEY"
}

该返回说明当前配置中心的加密功能还不能使用，因为没有为加密服务配置对应的密钥。

配置密钥

我们可以通过encrypt.key属性在配置文件中直接指定密钥信息（对称性密钥），比如：

encrypt.key=didispace

加入上述配置信息后，重启配置中心，再访问/encrypt/status端点，我们将得到如下内容：

{
  "status": "OK"
}

此时，我们配置中心的加密解密功能就已经可以使用了，不妨尝试访问一下/encrypt和/decrypt端点来进行加密和解密的功能。注意，这两个端点都是POST请求，加密和解密信息需要通过请求体来发送。比如，以curl命令为例，我们可以通过下面的方式调用加密与解密端点：

$ curl localhost:7001/encrypt -d didispace
3c70a809bf

$ curl localhost:7001/decrypt -d  3c70a809bfa
didispace

这里，我们通过配置encrypt.key参数来指定密钥的实现方式采用了对称性加密。这种方式实现比较简单，只需要配置一个参数即可。另外，我们也可以使用环境变量ENCRYPT_KEY来进行配置，让密钥信息外部化存储。

非对称加密

Spring Cloud Config的配置中心不仅可以使用对称性加密，也可以使用非对称性加密（比如：RSA密钥对）。虽然非对称性加密的密钥生成与配置相对复杂一些，但是它具有更高的安全性。

首先，我们需要通过keytool工具来生成密钥对。

• keytool是JDK中的一个密钥和证书管理工具。
• 它使用户能够管理自己的公钥/私钥对及相关证书，
• 用于（通过数字签名）自我认证（用户向别的用户/服务认证自己）或数据完整性以及认证服务。
• 在JDK 1.4以后的版本中都包含了这一工具，它的位置在：%JAVA_HOME%\bin\keytool.exe。

生成密钥的具体命令如下：

$ keytool -genkeypair -alias config-server -keyalg RSA -keystore config-server.keystore

keytool -genkeypair 
-alias config-server //alias
-keyalg RSA //key alg
-keystore config-server.keystore //keystore
输入密钥库口令:
再次输入新口令:
您的名字与姓氏是什么?
  [Unknown]:  zhaiyongchao
您的组织单位名称是什么?
  [Unknown]:  company
您的组织名称是什么?
  [Unknown]:  organization
您所在的城市或区域名称是什么?
  [Unknown]:  city
您所在的省/市/自治区名称是什么?
  [Unknown]:  province
该单位的双字母国家/地区代码是什么?
  [Unknown]:  china
CN=zhaiyongchao, OU=company, O=organization, L=city, ST=province, C=china是否正确?
  [否]:  y

输入 <config-server> 的密钥口令
        (如果和密钥库口令相同, 按回车):
再次输入新口令:

另外，如果我们不想逐步的输入那些提示信息，可以使用-dname来直接指定，而密钥库口令与密钥口令可使用-storepass和-keypass来直接指定。所以，我们可以通过下面的命令直接创建出与上述命令一样的密钥库：

$ keytool -genkeypair -alias config-server -keyalg RSA \ 
  -dname "CN=zhaiyongchao, OU=company, O=organization, L=city, ST=province, C=china" \
  -keypass 222222 \
  -keystore config-server.keystore \
  -storepass 111111 \
  -validity 365 \
  
$ keytool -genkeypair 
-alias config-server 
-keyalg RSA
-dname "CN=zhaiyongchao, OU=company, O=organization, L=city, ST=province, C=china"

-keypass 222222
-keystore config-server.keystore

-storepass 111111

默认情况下，上述命令创建的密钥只有90天有效期。如果我们想要调整它的有效期，可以通过增加-validity参数来实现，比如我们可以通过下面的命令，让密钥的有效期延长到一年：

- 如上

最终都会在命令的当前执行目录下生成一个config-server.keystore文件。下面，我们需要将它保存在配置中心的文件系统中的某个位置，比如放在当前的用户目录下，然后在配置中心中加入相关的配置信息：

encrypt.key-store.location=file://${user.home}/config-server.keystore
encrypt.key-store.alias=config-server
encrypt.key-store.password=111111
encrypt.key-store.secret=222222

如果我们将config-server.keystore放在配置中心的src/main/resource目录下，

• 也可以直接这样配置：encrypt.key-store.location=config-server.keystore。
• 另外，非对称加密的配置信息也可以通过环境变量的方式进行配置，它们对应的具体变量名如下：

ENCRYPT_KEY_STORE_LOCATION
ENCRYPT_KEY_STORE_ALIAS
ENCRYPT_KEY_STORE_PASSWORD
ENCRYPT_KEY_STORE_SECRET

通过环境变量来配置密钥库相关信息可以获得更好的安全性，所以我们可以将敏感的口令信息存储在配置中心的环境变量中是一种不错的选择。

5. 加密配置中的敏感信息

非Spring Boot原生就支持

而现实中，我们的配置文件中，其实包含着大量与安全相关的敏感信息，比如：数据库的账号密码、一些服务的密钥等。这些信息一旦泄露，对于企业的重要数据资产，那是相当危险的。

动手试试

下面我们将使用https://github.com/ulisesbocchio/jasypt-spring-boot这个开源项目提供的实现和插件，来帮助我们轻松的完成配置信息的加密。

设计一个参数和单元测试，用来输出这个配置信息

准备加密的配置：

datasource.password=didispace.com

用来输出配置信息的单元测试：

@Slf4j
@SpringBootTest
public class PropertiesTest {

    @Value("${datasource.password:}")
    private String password;

    @Test
    public void test() {
        log.info("datasource.password : {}", password);
    }

}

//datasource.password : didispace.com

执行这个单元测试，会输出：didispace.com

下面我们开始引入加密的操作！

第三步：在pom.xml中引入jasypt提供的Spring Boot Starter

<dependency>
    <groupId>com.github.ulisesbocchio</groupId>
    <artifactId>jasypt-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

在插件配置中加入：

<plugin>
    <groupId>com.github.ulisesbocchio</groupId>
    <artifactId>jasypt-maven-plugin</artifactId>
    <version>3.0.3</version>
</plugin>

第四步：在配置文件中加入加密需要使用的密码

jasypt.encryptor.password=didispace

同时，修改要加密的内容，用DEC()将待加密内容包裹起来，比如：

datasource.password=DEC(didispace.com)

第五步：使用jasypt-maven-plugin插件来给DEC()包裹的内容实现批量加密。

在终端中执行下面的命令：

mvn jasypt:encrypt -Djasypt.encryptor.password=didispace

注意：这里-Djasypt.encryptor.password参数必须与配置文件中的一致，不然后面会解密失败。

执行之后，重新查看配置文件，可以看到，自动变成了

datasource.password=ENC(/AL9nJENCYCh9Pfzdf2xLPsqOZ6HwNgQ3AnMybFAMeOM5GphZlOK6PxzozwtCm+Q)

jasypt.encryptor.password=didispace

其中，ENC()跟DEC()一样都是jasypt提供的标识，分别用来标识括号内的是加密后的内容和待加密的内容。

如果当前配置文件已经都是ENC()内容了，那么我们可以通过下面的命令来解密配置文件，查看原始信息：

mvn jasypt:decrypt -Djasypt.encryptor.password=didispace

该操作不会修改配置文件，只会在控制台输出解密结果，比如：

datasource.password=DEC(didispace.com)

jasypt.encryptor.password=didispace

第六步：此时，我们的配置文件中的敏感信息已经被ENC()修饰了，再执行一下单元测试，不出意外的话，依然可以得到之前一样的结果：

datasource.password : didispace.com

而此时，配置文件中已经是加密内容了，敏感信息得到了保护。

注意：如果在尝试的时候，出现报错：DecryptionException: Unable to decrypt，点击本文查看可能的原因 。

进一步思考

根据上面的步骤，爱思考的你，也许会发现这样的问题：虽然敏感信息是加密了，但是我们通过配置文件也能看到jasypt.encryptor.password信息，我们是不是通过利用这个再把原始信息解密出来，这样的话岂不是还是不安全？

上面的实现方式的确是会有这样的问题！所以，在实际应用的过程中，jasypt.encryptor.password的配置，可以通过运维小伙伴在环境变量或启动参数中注入，而不是由开发人员在配置文件中指定。

同时，为了应对更高的安全要求，jasypt也提供自定义的加密解密方式，这里就不做具体展开了，有兴趣的小伙伴可以前往jasypt的仓库查看使用细节。

代码示例

本文的完整工程可以查看下面仓库中2.x目录下的chapter1-5工程：

• Github：https://github.com/dyc87112/SpringBoot-Learning/
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/

使用jasypt加密配置的时候，报错：

• DecryptionException: Unable to decrypt

下面整理一下可能产生解密失败的几种可能：

第一种：推测解密失败的原因是加密和解密使用的密钥不一致，也就是jasypt.encryptor.password的配置和使用插件时候的参数传的不同。

第二种：没有安装不限长度的JCE版本（Unlimited Strength Java Cryptography Extension）。

我们可以从Oracle的官方网站中下载你所用Java版本对应的JCE安装包，比如：JCE8下载地址。它是一个压缩包，解压后可以看到下面三个文件：

README.txt
local_policy.jar
US_export_policy.jar

我们需要将local_policy.jar和US_export_policy.jar两个文件复制到$JAVA_HOME/jre/lib/security目录下，覆盖原来的默认内容，这样加密解密的准备工作就完成了。

6. 构建RESTful API与单元测试

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.3.RELEASE</version>
		<relativePath/>
	</parent>
	
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

• @Controller：修饰class，用来创建处理http请求的对象
• @RestController：Spring4之后加入的注解，
  • 原来在@Controller中返回json需要@ResponseBody来配合，
  • 如果直接用@RestController替代@Controller就不需要再配置@ResponseBody，默认返回json格式
• @RequestMapping：配置url映射。现在更多的也会直接用以Http Method直接关联的映射注解来定义，
  • 比如：GetMapping、PostMapping、DeleteMapping、PutMapping等

@RestController
@RequestMapping(value = "/users")     // 通过这里配置使下面的映射都在/users下
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    /**
     * 处理"/users/"的GET请求，用来获取用户列表
     *
     * @return
     */
    @GetMapping("/")
    public List<User> getUserList() {
        // 还可以通过@RequestParam从页面中传递参数来进行查询条件或者翻页信息的传递
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    /**
     * 处理"/users/"的POST请求，用来创建User
     *
     * @param user
     * @return
     */
    @PostMapping("/")
    public String postUser(@RequestBody User user) {
        // @RequestBody注解用来绑定通过http请求中application/json类型上传的数据
        users.put(user.getId(), user);
        return "success";
    }

    /**
     * 处理"/users/{id}"的GET请求，用来获取url中id值的User信息
     *
     * @param id
     * @return
     */
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // url中的id可通过@PathVariable绑定到函数的参数中
        return users.get(id);
    }

    /**
     * 处理"/users/{id}"的PUT请求，用来更新User信息
     *
     * @param id
     * @param user
     * @return
     */
    @PutMapping("/{id}")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    /**
     * 处理"/users/{id}"的DELETE请求，用来删除User
     *
     * @param id
     * @return
     */
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

使用@RequestBody替换了@ModelAttribute的参数

编写单元测试

下面针对该Controller编写测试用例验证正确性，具体如下。当然也可以通过浏览器插件等进行请求提交验证。

@RunWith(SpringRunner.class)
@SpringBootTest
public class Chapter21ApplicationTests {

    private MockMvc mvc;

    @Before
    public void setUp() {
        mvc = MockMvcBuilders.standaloneSetup(new UserController()).build();
    }

    @Test
    public void testUserController() throws Exception {
        // 测试UserController
        RequestBuilder request;

        // 1、get查一下user列表，应该为空
        request = get("/users/");
        mvc.perform(request)
                .andExpect(status().isOk())
                .andExpect(content().string(equalTo("[]")));

        // 2、post提交一个user
        request = post("/users/")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"id\":1,\"name\":\"测试大师\",\"age\":20}");
        mvc.perform(request)
                .andExpect(content().string(equalTo("success")));

        // 3、get获取user列表，应该有刚才插入的数据
        request = get("/users/");
        mvc.perform(request)
                .andExpect(status().isOk())
                .andExpect(content().string(equalTo("[{\"id\":1,\"name\":\"测试大师\",\"age\":20}]")));

        // 4、put修改id为1的user
        request = put("/users/1")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"name\":\"测试终极大师\",\"age\":30}");
        mvc.perform(request)
                .andExpect(content().string(equalTo("success")));

        // 5、get一个id为1的user
        request = get("/users/1");
        mvc.perform(request)
                .andExpect(content().string(equalTo("{\"id\":1,\"name\":\"测试终极大师\",\"age\":30}")));

        // 6、del删除id为1的user
        request = delete("/users/1");
        mvc.perform(request)
                .andExpect(content().string(equalTo("success")));

        // 7、get查一下user列表，应该为空
        request = get("/users/");
        mvc.perform(request)
                .andExpect(status().isOk())
                .andExpect(content().string(equalTo("[]")));

    }

}

对MockMvc不熟悉的读者，可能会碰到一些函数不存在而报错。必须引入下面这些静态函数的引用：

import static org.hamcrest.Matchers.equalTo;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

这里相较1.x版本教程中，主要有两个地方不同。测试类采用@RunWith(SpringRunner.class)和@SpringBootTest修饰启动；另外，由于POST和PUT接口的参数采用@RequestBody注解，所以提交的会是一个json字符串，而不是之前的参数形式，这里在定义请求的时候使用contentType(MediaType.APPLICATION_JSON)指定提交内容为json格式，使用content传入要提交的json字符串。如果用@ModelAttribute的话就得用param方法添加参数，具体可以看1.x版本的教程。

代码示例

本文的相关例子可以查看下面仓库中的chapter2-1目录：

<version>2.5.0</version>
<version>2.6.2</version> //boot 这个版本 和 以上吧，只需要一个注解，即可。

import org.junit.jupiter.api.Test;

@SpringBootTest

@Test
public void test(){}
//没有 @Before 注解，还没研究

7. Swagger2

引入pom ，开启注解

在pom.xml中加入依赖，具体如下：

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

第二步：应用主类中添加@EnableSwagger2Doc注解，具体如下

@EnableSwagger2Doc
@SpringBootApplication
public class Chapter22Application {

    public static void main(String[] args) {
        SpringApplication.run(Chapter22Application.class, args);
    }

}

使用属性 进行配置

第三步：application.properties中配置文档相关内容，比如

swagger.title=spring-boot-starter-swagger //标题
swagger.description=Starter for swagger 2.x	//描述
swagger.version=1.4.0.RELEASE	//版本
swagger.license=Apache License, Version 2.0	//许可证
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html		//许可证URL
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger //服务条款
swagger.contact.name=didi	//维护人
swagger.contact.url=http://blog.didispace.com	//维护人URL
swagger.contact.email=dyc87112@qq.com	//email
swagger.base-package=com.didispace	//扫描的包
swagger.base-path=/**		//基本URL规则

各参数配置含义如下：

• swagger.title：标题
• swagger.description：描述
• swagger.version：版本
• swagger.license：许可证
• swagger.licenseUrl：许可证URL
• swagger.termsOfServiceUrl：服务条款URL
• swagger.contact.name：维护人
• swagger.contact.url：维护人URL
• swagger.contact.email：维护人email
• swagger.base-package：swagger扫描的基础包，默认：全扫描
• swagger.base-path：需要处理的基础URL规则，默认：/**

更多配置说明可见官方说明：https://github.com/SpringForAll/spring-boot-starter-swagger

第四步：启动应用，访问：http://localhost:8080/swagger-ui.html，就可以看到如下的接口文档页面：

swagger2注解的说明

关于各个接口的描述还都是英文或遵循代码定义的名称产生的。这些内容对用户并不友好，所以我们需要自己增加一些说明来丰富文档内容。如下所示，我们通过

• @Api，@ApiOperation注解来给API增加说明、
• 通过@ApiImplicitParam、
  • @ApiModel、@ApiModelProperty注解来给参数增加说明。

比如下面的例子：

@Api(tags = "用户管理") //写在 类上
@RestController
@RequestMapping(value = "/users")     // 通过这里配置使下面的映射都在/users下
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "获取用户列表") //写在 方法上
    public List<User> getUserList() {
        List<User> r = new ArrayList<>(users.values());
        return r;
    }

    @PostMapping("/")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}") //ApiImplicitParam 参数的说明
    @ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")
    @ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

@Data
@ApiModel(description="用户实体") //实体类的说明
public class User {

    @ApiModelProperty("用户编号")	//实体类的属性
    private Long id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;

}

完成上述代码添加后，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，就能看到下面这样带中文说明的文档了（其中标出了各个注解与文档元素的对应关系以供参考）：

8. JSR-303实现请求参数校验

什么是JSR？

JSR是Java Specification Requests的缩写，意思是Java 规范提案。

• 是指向JCP(Java Community Process)提出新增一个标准化技术规范的正式请求。
• 任何人都可以提交JSR，以向Java平台增添新的API和服务。JSR已成为Java界的一个重要标准。

JSR-303定义的是什么标准？

JSR-303 是JAVA EE 6 中的一项子规范，叫做Bean Validation，

• Hibernate Validator 是 Bean Validation 的参考实现 .
• Hibernate Validator 提供了 JSR 303 规范中所有内置 constraint 的实现，除此之外还有一些附加的 constraint。

Bean Validation中内置的constraint

pecification 
英 /ˌspesɪfɪˈkeɪʃ(ə)n/  美 /ˌspesɪfɪˈkeɪʃn/  全球(加拿大)  
简明 牛津 新牛津  韦氏  柯林斯 例句  百科
n. 规格，规范，明细单，说明书；明确说明，详述；（申请专利用的）发明物说明书

community 
英 /kəˈmjuːnəti/  美 /kəˈmjuːnəti/  全球(美国)  
简明 牛津 新牛津  韦氏  柯林斯 例句  百科
n. 社区，社会；（由同国籍、同宗教等构成的）群体，界；（多个国家的）共同体；归属感；（动植物的）群落

constraint 
英 /kənˈstreɪnt/  美 /kənˈstreɪnt/  全球(美国)  
简明 牛津 新牛津  韦氏  柯林斯 例句  百科
n. 限制，束缚；克制，拘束

    import javax.validation.constraints.*;
    
    @NotNull
    @Max(100)
    @Min(10)
    @Size(min = 2, max = 5) //用在string上

Hibernate Validator附加的constraint

    import org.hibernate.validator.constraints.Length;
	import org.hibernate.validator.constraints.Range;
    
    @Range(min = 1,max = 6,message = "不合规")
    @Length(min = 1,max = 6,message = "不合规")

动手实践

快速入门

我们先来做一个简单的例子，比如：定义字段不能为Null。只需要两步

第一步：在要校验的字段上添加上@NotNull注解，具体如下：

@Data
@ApiModel(description="用户实体")
public class User {

    @ApiModelProperty("用户编号")
    private Long id;

    @NotNull
    @ApiModelProperty("用户姓名")
    private String name;

    @NotNull
    @ApiModelProperty("用户年龄")
    private Integer age;

}

配合 BindingResult

第二步：在需要校验的参数实体前添加@Valid注解，具体如下：

    @PostMapping("/")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public String postUser(@Valid @RequestBody User user, BindingResult bindingResult) {

        //包含错误
        if (bindingResult.hasErrors()) {
            List list = new ArrayList();

            for (FieldError fieldError : bindingResult.getFieldErrors()) {
                list.add(fieldError.getDefaultMessage());
            }
            return list.toString();
        }

        users.put(user.getId(), user);
        return "success";
    }


[不是一个合法的电子邮件地址, 个数必须在2和5之间, 最小不能小于10]

完成上面配置之后，启动应用，并用POST请求访问localhost:8080/users/接口，body使用一个空对象，{}。你可以用Postman等测试工具发起，也可以使用curl发起，比如这样：

curl -X POST \
  http://localhost:8080/users/ \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 72745d04-caa5-44a1-be84-ba9c115f4dfb' \
  -H 'cache-control: no-cache' \
  -d '{
    
}'

不出意外，你可以得到如下结果：

{
    "timestamp": "2019-10-05T05:45:19.221+0000", //请求时间
    "status": 400,		//状态码
    "error": "Bad Request",		//错误描述
    "errors": [		//具体错误的原因
        {
            "codes": [
                "NotNull.user.age",
                "NotNull.age",
                "NotNull.java.lang.Integer",
                "NotNull"
            ],
            "arguments": [
                {
                    "codes": [
                        "user.age",
                        "age"
                    ],
                    "arguments": null,
                    "defaultMessage": "age",
                    "code": "age"
                }
            ],
            "defaultMessage": "不能为null", //就是 @NotNull(message = "用户姓名啦啦啦不能为空")
            "objectName": "user",
            "field": "age",
            "rejectedValue": null,
            "bindingFailure": false,
            "code": "NotNull"
        } //存在多个
    ],
    "message": "Validation failed for object='user'. Error count: 2",	//错误消息
    "path": "/users/"		//请求路径
}

其中返回内容的各参数含义如下：

• timestamp：请求时间
• status：HTTP返回的状态码，这里返回400，即：请求无效、错误的请求，通常参数校验不通过均为400
• error：HTTP返回的错误描述，这里对应的就是400状态的错误描述：Bad Request
• errors：具体错误原因，是一个数组类型；因为错误校验可能存在多个字段的错误，比如这里因为定义了两个参数不能为Null，所以存在两条错误记录信息
• message：概要错误消息，返回内容中很容易可以知道，这里的错误原因是对user对象的校验失败，其中错误数量为2，而具体的错误信息就定义在上面的errors数组中
• path：请求路径

请求的调用端在拿到这个规范化的错误信息之后，就可以方便的解析并作出对应的措施以完成自己的业务逻辑了。

尝试一些其他校验

在完成了上面的例子之后，我们还可以增加一些校验规则，比如：校验字符串的长度、校验数字的大小、校验字符串格式是否为邮箱等。下面我们就来定义一些复杂的校验定义，比如：

@Data
@ApiModel(description="用户实体")
public class User {

    @ApiModelProperty("用户编号")
    private Long id;

    @NotNull
    @Size(min = 2, max = 5) //用户名 必须 2-5
    @ApiModelProperty("用户姓名")
    private String name;

    @NotNull
    @Max(100)
    @Min(10) //年龄 必须 10 到 100
    @ApiModelProperty("用户年龄")
    private Integer age;

    @NotNull
    @Email
    @ApiModelProperty("用户邮箱")
    private String email;

}

发起一个可以出发name、age、email都校验不通过的请求，比如下面这样：

curl -X POST \
  http://localhost:8080/users/ \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 114db0f0-bdce-4ba5-baf6-01e5104a68a3' \
  -H 'cache-control: no-cache' \
  -d '{
    "name": "abcdefg", //name太长
    "age": 8, //年龄 不和规矩
    "email": "aaaa" //错误
}'

我们将得到如下的错误返回：

{
    "timestamp": "2019-10-05T06:24:30.518+0000",
    "status": 400,
    "error": "Bad Request",
    "errors": [
        {
            "codes": [
                "Size.user.name",
                "Size.name",
                "Size.java.lang.String",
                "Size"
            ],
            "arguments": [
                {
                    "codes": [
                        "user.name",
                        "name"
                    ],
                    "arguments": null,
                    "defaultMessage": "name",
                    "code": "name"
                },
                5,
                2
            ],
            "defaultMessage": "个数必须在2和5之间",
            "objectName": "user",
            "field": "name",
            "rejectedValue": "abcdefg",
            "bindingFailure": false,
            "code": "Size"
        }
    ],
    "message": "Validation failed for object='user'. Error count: 3",
    "path": "/users/"
}

从errors数组中的各个错误明细中，知道各个字段的defaultMessage，可以看到很清晰的错误描述。

Swagger文档中的体现

可能有读者会问了，我的接口中是定了这么多。上一篇教程中，不是还教了如何自动生成文档么，那么对于参数的校验逻辑该如何描述呢？

这里要分两种情况，Swagger自身对JSR-303有一定的支持，但是支持的并那么完善，并没有覆盖所有的注解的。

比如，上面我们使用的注解是可以自动生成的，启动上面我们的实验工程，然后访问http://localhost:8080/swagger-ui.html，在Models不是，我们可以看到如下图所示的内容：

http://localhost:8080/swagger-ui.html
http://xxxx/swagger-ui/index.html

其中：name和age字段相比上一篇教程中的文档描述，多了一些关于校验相关的说明；而email字段则没有体现相关校验说明。目前，Swagger共支持以下几个注解：@NotNull、@Max、@Min、@Size、@Pattern。在实际开发过程中，我们需要分情况来处理，对于Swagger支自动生成的可以利用原生支持来产生，如果有部分字段无法产生，则可以在@ApiModelProperty注解的描述中他，添加相应的校验说明，以便于使用方查看。

番外：也许你会有这些疑问

当请求参数校验出现错误信息的时候，错误格式可以修改吗？

答案是肯定的。这里的错误信息实际上由Spring Boot的异常处理机制统一组织并返回的，我们将在后面的教程中详细介绍，Spring Boot是如何统一处理异常返回以及我们该如何定时异常返回。

spring-boot-starter-validation是必须的吗？

有读者之前问过，看到很多教程都写了还要引入spring-boot-starter-validation依赖，这个依赖到底是否需要？（本篇中并没有引入）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

spring-boot-starter-validation依赖主要是为了引入下面这个依赖：

<dependency>
   <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.14.Final</version>
    <scope>compile</scope>
</dependency>

在Spring Boot 2.1版本中，该依然其实已经包含在了spring-boot-starter-web依赖中，并不需要额外引入

本文的完整工程可以查看下面仓库中的chapter2-3目录：

9. Swagger接口分类与各元素排序

默认情况下，Swagger是以Controller为单位，对接口进行分组管理的。这个分组的元素在Swagger中称为Tag，但是这里的Tag与接口的关系并不是一对多的，它支持更丰富的多对多关系。

默认分组

首先，我们通过一个简单的例子，来看一下默认情况，Swagger是如何根据Controller来组织Tag与接口关系的。定义两个Controller，分别负责教师管理与学生管理接口，比如下面这样：

@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @GetMapping("/xxx")
    public String xxx() {
        return "xxx";
    }

}

@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation("获取学生清单")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

}

启动应用之后，我们可以看到Swagger中这两个Controller是这样组织的：

自定义默认分组的名称

接着，我们可以再试一下，通过@Api注解来自定义Tag，比如这样：

@Api(tags = "教师管理")
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = "学生管理")
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    // ...

}

再次启动应用之后，我们就看到了如下的分组内容，代码中@Api定义的tags内容替代了默认产生的teacher-controller和student-controller。

合并Controller分组

到这里，我们还都只是使用了Tag与Controller一一对应的情况，Swagger中还支持更灵活的分组！从@Api注解的属性中，相信聪明的读者一定已经发现tags属性其实是个数组类型：

我们可以通过定义同名的Tag来汇总Controller中的接口，比如我们可以定义一个Tag为“教学管理”，让这个分组同时包含教师管理和学生管理的所有接口，可以这样来实现：

@Api(tags = {"教师管理", "教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = {"学生管理", "教学管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    // ...

}

最终效果如下：

更细粒度的接口分组

通过@Api可以实现将Controller中的接口合并到一个Tag中，但是如果我们希望精确到某个接口的合并呢？比如这样的需求：“教学管理”包含“教师管理”中所有接口以及“学生管理”管理中的“获取学生清单”接口（不是全部接口）。

那么上面的实现方式就无法满足了。这时候发，我们可以通过使用@ApiOperation注解中的tags属性做更细粒度的接口分类定义，比如上面的需求就可以这样子写：

@Api(tags = {"教师管理","教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @ApiOperation(value = "xxx")
    @GetMapping("/xxx")
    public String xxx() {
        return "xxx";
    }

}

@Api(tags = {"学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation(value = "获取学生清单", tags = "教学管理")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    @ApiOperation("获取教某个学生的老师清单")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }

    @ApiOperation("创建一个学生")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }
}

效果如下图所示：

内容的顺序

在完成了接口分组之后，对于接口内容的展现顺序又是众多用户特别关注的点，其中主要涉及三个方面：分组的排序、接口的排序以及参数的排序，下面我们就来逐个说说如何配置与使用。

分组的排序

关于分组排序，也就是Tag的排序。目前版本的Swagger支持并不太好，通过文档我们可以找到关于Tag排序的配置方法。

第一种：原生Swagger用户，可以通过如下方式：

第二种：Swagger Starter用户，可以通过修改配置的方式：

swagger.ui-config.tags-sorter=alpha

似乎找到了希望，但是其实这块并没有什么可选项，一看源码便知：

public enum TagsSorter {
  ALPHA("alpha");

  private final String value;

  TagsSorter(String value) {
    this.value = value;
  }

  @JsonValue
  public String getValue() {
    return value;
  }

  public static TagsSorter of(String name) {
    for (TagsSorter tagsSorter : TagsSorter.values()) {
      if (tagsSorter.value.equals(name)) {
        return tagsSorter;
      }
    }
    return null;
  }
}

是的，Swagger只提供了一个选项，就是按字母顺序排列。那么我们要如何实现排序呢？这里笔者给一个不需要扩展源码，仅依靠使用方式的定义来实现排序的建议：为Tag的命名做编号。比如：

@Api(tags = {"1-教师管理","3-教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = {"2-学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation(value = "获取学生清单", tags = "3-教学管理")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    // ...

}

由于原本存在按字母排序的机制在，通过命名中增加数字来帮助排序，可以简单而粗暴的解决分组问题，最后效果如下：

接口的排序

在完成了分组排序问题（虽然不太优雅…）之后，在来看看同一分组内各个接口该如何实现排序。同样的，凡事先查文档，可以看到Swagger也提供了相应的配置，下面也分两种配置方式介绍：

第一种：原生Swagger用户，可以通过如下方式：

第二种：Swagger Starter用户，可以通过修改配置的方式：

swagger.ui-config.operations-sorter=alpha

很庆幸，这个配置不像Tag的排序配置没有可选项。它提供了两个配置项：alpha和method，分别代表了按字母表排序以及按方法定义顺序排序。当我们不配置的时候，改配置默认为alpha。两种配置的效果对比如下图所示：

参数的排序

完成了接口的排序之后，更细粒度的就是请求参数的排序了。默认情况下，Swagger对Model参数内容的展现也是按字母顺序排列的。所以之前教程中的User对象在文章中展现如下：

如果我们希望可以按照Model中定义的成员变量顺序来展现，那么需要我们通过@ApiModelProperty注解的position参数来实现位置的设置，比如：

@Data
@ApiModel(description = "用户实体")
public class User {

    @ApiModelProperty(value = "用户编号", position = 1)
    private Long id;

    @NotNull
    @Size(min = 2, max = 5)
    @ApiModelProperty(value = "用户姓名", position = 2)
    private String name;

    @NotNull
    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用户年龄", position = 3)
    private Integer age;

    @NotNull
    @Email
    @ApiModelProperty(value = "用户邮箱", position = 4)
    private String email;

}

position 
英 /pəˈzɪʃn/  美 /pəˈzɪʃn/  全球(英国)  
简明 牛津 新牛津  韦氏  柯林斯 例句  百科
n. 位置，地点；恰当位置，正确位置；阵地；姿势，安置方式；处境，状况；观点，立场；地位，身份；职务，职位；（比赛、竞赛中的）名次；
v. 安置，使处于；为（产品，服务，业务）打开销路，确立（产品，服务，业务的）行业地位

本文的完整工程可以查看下面仓库中的chapter2-4

10. Swagger静态文档的生成

我们可能只需要提供静态文档给其他对接方的时候，我们要如何快速轻便的产生静态API文档呢？

Swagger2Markup。

Swagger2Markup简介

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

生成 AsciiDoc 文档

生成 AsciiDoc 文档的方式有两种：

通过Java代码来生成

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

<dependencies>
    ...

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

本身这个工具主要就临时用一下，所以这里我们把scope设置为test，这样这个依赖就不会打包到正常运行环境中去。

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

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {

    @Test
    public void generateAsciiDocs() throws Exception {

        URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
        Path outputDirectory = Paths.get("src/docs/asciidoc/generated");

        //    输出Ascii格式 
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();


        Swagger2MarkupConverter.from(remoteSwaggerFile)
                .withConfig(config)
                .build()
                .toFolder(outputDirectory);
    }

}

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

• MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP，分别定义了其他格式，后面会具体举例。
• from(remoteSwaggerFile：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
• toFolder(outputDirectory)：指定最终生成文件的具体目录位置

在执行了上面的测试用例之后，我们就能在当前项目的src目录下获得如下内容：

src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc

可以看到，这种方式在运行之后就生成出了4个不同的静态文件。

输出到单个文件

如果不想分割结果文件，也可以通过替换toFolder(Paths.get("src/docs/asciidoc/generated")为toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个单一的文件中，这样可以最终生成html的也是单一的。

通过 Maven 插件来生成

除了通过上面编写Java代码来生成的方式之外，swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式，完全可以通过在pom.xml中增加如下插件来完成静态内容的生成。

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated-by-plugin</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

在使用插件生成前，需要先启动应用。然后执行插件，就可以在src/docs/asciidoc/generated-by-plugin目录下看到也生成了上面一样的adoc文件了。

生成HTML asciidoctor

在完成了从Swagger文档配置文件到AsciiDoc的源文件转换之后，就是如何将AsciiDoc转换成可部署的HTML内容了。这里继续在上面的工程基础上，引入一个Maven插件来完成。

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
   	    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
   	    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
   	    <backend>html</backend>
   	    <sourceHighlighter>coderay</sourceHighlighter>
   	    <attributes>
            <toc>left</toc>
  	    </attributes>
  	</configuration>
</plugin>

通过上面的配置，执行该插件的asciidoctor:process-asciidoc命令之后，就能在src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。在完成生成之后，可以直接通过浏览器来看查看，你就能看到类似下图的静态部署结果：

是不是感觉似曾相识呢？是的，Spring Cloud的E版之前的文档也是这样的！！！

Markdown 与 Confluence 的支持

要生成Markdown和Confluence的方式非常简单，与上一篇中的方法类似，只需要修改一个参数即可。

生成 Markdown 和 Confluence 文档

生成方式有一下两种：

• 通过Java代码来生成：只需要修改withMarkupLanguage属性来指定不同的格式以及toFolder属性为结果指定不同的输出目录。

生成markdown的代码片段：

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/markdown/generated");

//    输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(remoteSwaggerFile)
    .withConfig(config)
    .build()
    .toFolder(outputDirectory);

生成confluence的代码片段：

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/confluence/generated");

//    输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(remoteSwaggerFile)
    .withConfig(config)
    .build()
    .toFolder(outputDirectory);

在执行了上面的设置内容之后，我们就能在当前项目的src目录下获得如下内容：

src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md

可以看到，运行之后分别在markdown和confluence目录下输出了不同格式的转换内容。如果读者想要通过插件来生成，直接参考上一节内容，只需要修改插件配置中的swagger2markup.markupLanguage即可支持输出其他格式内容。

最后，我们一起来看看生成的Markdown和Confluence文档要怎么使用

Markdown的部署

Markdown目前在文档编写中使用非常常见，所以可用的静态部署工具也非常多，比如：Hexo、Jekyll等都可以轻松地实现静态化部署，也可以使用一些SaaS版本的文档工具，比如：语雀等。具体使用方法，这里按照这些工具的文档都非常详细，这里就不具体介绍了。

Confluence的部署

相信很多团队都使用Confluence作为文档管理系统，所以下面具体说说Confluence格式生成结果的使用。

第一步：在Confluence的新建页面的工具栏中选择{}Markup

第二步：在弹出框的Insert选项中选择Confluence Wiki，然后将生成的txt文件中的内容，黏贴在左侧的输入框中；此时，在右侧的阅览框可以看到如下图的效果了。

注意：所以Insert选项中也提供了Markdown格式，我们也可以用上面生成的Markdown结果来使用，但是效果并不好，所以在Confluence中使用专门的生成结果为佳。

本文的完整工程可以查看下面仓库中的chapter2-5目录：