博客

原文地址见

Github Wiki

Spring MVC 注解支持表

注释 / Swagger 注解对应表

本插件支持读取注释 / 注解信息来生成文档，因为 Swagger 用户比较多，考虑到最小成本改造，注解采用的正是 Swagger 这一套，注释则是自己随便定义了一些 tag，具体见下表格！

更多有用的注释/注解

虽然提到了注解，但更多时候，我都是增加注释来完善文档的，毕竟注解的侵入性较高，还需要增加依赖 jar。

注释

@ 或 #，其实都一样

可能你已经注意到了，上面的表格对应注释总是有两种写法，但他们其实只有前缀不同。

我在代码中解析时，两个符号都会判断，等同对待，因此任一种写法都是 OK 的。

之所以会加一个

#

开头，主要是考虑大部分同学并不知道（我也不知道）如何设置自定义注释 tag，以确保 IDEA 某条规则解析时不会以警告处理。而

#

，反而不会触发这条报警规则！

注释还是注解？ @important 说了算！

虽然你有注解，但我偏喜欢用注释来生成文档，此时需要使用此注解来告诉插件，使用注释而忽略注解！

之所以这么设计，是因为我虽然更偏爱注释，但也知道大部分注释都是不完整的，而注解则一般较为完整；因此设计优先级时，存在注解则优先使用注解的信息；

于是，我们需要一种方式来提高注释的优先级；此时我便想到了 CSS 的

!important

，于是添加了这个注解。

该注释值为

true/false

，一般写作

#important

即可。

该注释支持位置如下：类上，字段上，方法上，参数中（即

@param

这行，注意参数的注释以

xx=xx

格式，不同于其他三处写法）

接口并非成功或失败？有多种状态？试试 @code！

若您的接口有多个返回状态码，一般为错误码；

您可使用

@code 50001 错误信息xxxx

来描述这个状态，若有多个，则多写几行即可！

请看一个示例：

/**
 * 新增一个用户
 *
 * @param createUserRequest 用户信息
 * @return 操作是否成功
 * #hiddenResponse totalCount
 * #code 10001 用户昵称已存在
 * #code 10002 用户年龄范围无效， 即用户年龄需在0~200之间的数字
 */
@PostMapping("/createUser")
public BaseResponse<Boolean> createUser(CreateUserRequest createUserRequest) {
    return BaseResponse.success();
}

生成文档如下图，将多出一段 Code 含义信息表格

友情提示，该功能 Swagger 也支持，请翻到看下面注解篇查看！

某个入参字段或返回值字段不需要出现在这个接口，但会出现在那个接口，怎么办？

有时候，部分数据传输类被多个接口复用，但某个接口可能不需要某个字段（不论入参出参），此时我们可以使用

@hiddenRequest

和

@hiddenResponse

来排除字段；

类似的，你也可以使用

@onlyRequest

和

@onlyResponse

来指定仅需要的字段。

其中

request

后缀指代入参，

response

后缀指代出参。

另外，排除和仅包含只能出现一个，否则排除优先级更高，另一个则不会起作用。

关于出参，用法比较确定，毕竟只有一个返回值，以此为根对象，指定字段非常方便；如上个示例中我就隐藏了

totalCount

这个分页相关的出参，其为返回类型下的一个字段；也可以使用

data.xxx

这种格式，通过

.

来指定多层结构下的字段。

而入参，我采用的方式是以

Spring MVC

的解析方式为准，即若所有参数以

application/x-www-form-urlencoded

方式绑定，则表单中的组件名称与变量名称对应；

且当参数为对象类型时，其下的字段与表单中组件名称一致，而不是带有参数的变量名为前缀；如上个示例中，

createUserRequest

这个变量就是如此。

总计就是不带有参数变量名为前缀的写法。

这与

knife4j

定义的

@ApiOperationSupport

注解中

includeParameters，ignoreParameters

并不相同；

不过您不用担心，我在程序中已经做了处理，使用其注解时，按照

knife4j

的写法来即可，插件依然能正确识别。

使用 @json 或 @date 来指定日期时间格式

两个注释作用一样，

@date

的优先级高；

此注释只能用于字段上。

示例：

/**
 * 开始时间（精度为天）
 * @json yyyy-MM-dd
 * @data yyyy-MM-dd
 */
private Date startTime;

生成的文档的结果如下：

{
  "startTime": "2022-05-29"
}

此注释依据

@JsonFormat

和

@DateTimeFormat

注解字段

pattern

演化而来，因此使用注解也会识别，都存在时，注解优先级高！（

@important

此时无效）

使用 @noResponse 来取消 Postman 请求下的示例生成。

如题，添加注释后，生成的 Postman 请求下，返回示例将不生成！

此注释可用于类上，方法上，方法上优先级高（就近原则）。

使用 @guid 和 @random 来控制示例值的生成

您可通过

@guid

来指定示例值为一个 GUID；

使用

@random

来指定字符串示例值的生成时随机的（有字段描述时，非随机，此时可用注释指定为随机，无字段描述时，默认随机）；

这两个注释仅适用于字符串类型的字段；

此注释可用于，方法参数上，字段上。

注解

与 @code 对应的 @ApiResponse 和 @ApiResponses

• 
@ApiResponse

  的
  
code

  和
  
message

  分别对应 Code 和 含义
• 
@ApiResponses

  则用于包含多个
  
@ApiResponse


与 @onlyRequest/@hiddenRequest 对应的 @ApiOperationSupport

• 注意此注解仅
  
knife4j

  拥有。
• 上面有提到，
  
knife4j

  的写法是包含参数变量作为前缀的，和我注释的写法是不一样的，请不要混淆两者！
• 
knife4j

  仅支持入参，不支持出参，而我的注释是均支持，您可以在注解的基础上，使用注释来设置出参，这样是可以生效的。（这点适用于绝大多数更多注释）

与 @json/@date 对应的 @JsonFormat 和 @DateTimeFormat

• 
@JsonFormat

  的
  
pattern

  字段值与注释
  
@json

  对应。
• 
@DateTimeFormat

  的
  
pattern

  字段值与注释
  
@date

  对应。

Hibernate validator 的部分注解支持

• 
@NotNull / @NotEmpty / @NotBlank

  ：包含此三个任意一个注解的字段或参数，其是否必填会被设置为 true。
• 
@Length

  ：包含此注解时，其字段
  
max / min

  指定了字符长度最大值和最小值，其他参考信息列会多出相应的描述。
• 
@Range / @Min / @Max

  ：指定了数字的范围，其他参考信息列会多出相应的描述。

以上的 Hibernate validator 注解均支持在参数上或字段上。

除文档生成外更多功能

导出到 Postman

直接在项目上右键（或某个目录/某个类/任意多选亦可），然后点击

Export Api Interface to Postman

的按钮，如下图



生成的结果文件在文档跟目录（一般为项目路径/api-doc）下 postman 目录下，有个

xxx.postman_collection.json

，然后在 Postman 导入界面选择此文件即可。

导出到 Postman 有两种模式

• 离线模式，生成文件到 postman 目录下。
• 在线模式，通过配置文件指定 Postman 的 Api Key，可直接通过 api 生成到你的 workspace 下（但无法控制生成到哪个 workspace 下，Postman 提供的 Api 不够完善的问题。）

另外，当仅选择一个类右键时，会根据此类为标识来生成新的 Collection（默认以项目名或在配置文件中指定）；

这样做的好处是，不会因为调试某个类把原来的 Collection 覆盖掉。

使用 Search Everywhere 根据 url 搜索并快速跳转到接口定义

双击

Shift

进入

Search Everywhere

后切换到 Api，或使用快捷键

Ctrl + \

或

Ctrl + Alt + N

进入如下图界面。

此时您可通过 url 或接口描述来搜索并跳转到该接口。

使用智能上下文或后缀快速生成实体类的所有 set 方法 / get 方法

以下展示后缀的使用方法，但使用智能上下文得到的效果是类似的，只是个人认为后缀效率更高一丢丢！

下面演示所使用的基础类

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
class Foo {

    private Integer testInt;

    private Long testLong;

    private Float testFloat;

    private Double testDouble;

    private Boolean testBoolean;

}

生成 set

public void usage01() {
    // 用法1, 生成所有 set 方法, 带默认值, 通过 postfix
    Foo foo = new Foo();
    // 取消下面的注释, 光标位于 allset 后面, 按下 Tab 键
//        foo.allset
    // 即可得到下面结果, 且 foo.allset 会自动消失
    foo.setTestInt(0);
    foo.setTestLong(0L);
    foo.setTestFloat(0f);
    foo.setTestDouble(0D);
    foo.setTestBoolean(false);
}

生成 get

public void usage03() {
    // 用法3, 生成所有 get 方法, 通过 postfix
    Foo foo = new Foo();
    // 取消下面的注释, 光标位于 allget 后面, 按下 Tab 键
//        foo.allget
    // 即可得到下面结果, 且 foo.allget 会自动消失
    Integer testInt = foo.getTestInt();
    Long testLong = foo.getTestLong();
    Float testFloat = foo.getTestFloat();
    Double testDouble = foo.getTestDouble();
    Boolean testBoolean = foo.getTestBoolean();
}

Lombok 的 @Builder 快速生成所有赋值方法的调用链

public void usage04() {
    // 用法4, 生成所有 set 方法, 通过 builder, 通过 postfix
    // 取消下面的注释, 光标位于 allbuilder 后面, 按下 Tab 键
//        Foo.builder().allbuilder
    // 即可得到下面结果
    Foo foo = Foo.builder()
            .testInt(0)
            .testLong(0L)
            .testFloat(0f)
            .testDouble(0D)
            .testBoolean(false)
            .build();
}

根据一段含有源对象（a）/目标对象（b）的 b.setXxx(a.getXxx()) 方法代码生成所有 set 方法以快速实现对象转换

public void usage05() {
    // 用法5, 将 src 的数据赋值给 dest, 常用于两个不同类直接进行 convert(需字段名称相同), 通过 postfix
    Foo src = new Foo();
    Foo dest = new Foo();
    // 取消下面的注释, 光标位于 convert 后面, 按下 Tab 键
//        dest.setTestInt(src.getTestInt());.convert
    // 即可得到下面结果
    dest.setTestInt(src.getTestInt());
    dest.setTestLong(src.getTestLong());
    dest.setTestFloat(src.getTestFloat());
    dest.setTestDouble(src.getTestDouble());
    dest.setTestBoolean(src.getTestBoolean());
}

根据一个入参为源对象（a），返回值为目标对象（b）的方法声明，生成对象转换方法

public Foo usage09(Foo src) {
    // 用法9 通过在方法名称上触发 Show Context Actions, 快捷键(如 Alt + Enter 或右键菜单选择)
    //  可看到 Generate Convert，选中后生成下面注释里的内容（不包含 return null;)
//        Foo foo = new Foo();
//        foo.setTestInt(src.getTestInt());
//        foo.setTestLong(src.getTestLong());
//        foo.setTestFloat(src.getTestFloat());
//        foo.setTestDouble(src.getTestDouble());
//        foo.setTestBoolean(src.getTestBoolean());
//        return foo;
    return null;
}

上面这些代码在

示例代码块

的

cn.gudqs.example.genset.GenerateSetterAndGetterUsage

下。

欢迎 Clone 体验。