@ApiModelProperty注解example属性为何出现多余反斜杠？

我之前也踩过Swagger这俩插件转义重复的坑，给你几个实用的解决办法：

1. 改用@Example注解定义复杂示例（推荐） #

直接在@ApiModelProperty的example属性里写带转义的JSON字符串很容易触发重复转义问题。换成Swagger的@Example注解来定义示例，能更清晰地处理复杂JSON结构，从根源避免转义混乱。

如果你用的是OpenAPI 3.0+（对应swagger-v3依赖）： #

import io.swagger.v3.oas.annotations.media.Example;
import io.swagger.v3.oas.annotations.media.Examples;
import io.swagger.v3.oas.annotations.media.Schema;

// 替换原@ApiModelProperty为@Schema
@Schema(description = "Сенсоры устройства")
@Examples(value = {
    @Example(
        value = "{\"BATTERY\":67, \"VOLUME\":50, \"AIRPLANE\":false, \"ALARM\":true, \"CHARGE\":false, \"MUTE\":false, \"SCREEN\":true, \"WIFI\":true, \"LOCATION\": {\"latitude\":55.78409222171274,\"precision\":65.0,\"time\":\"2017-09-29T14:55:00Z\",\"detectionTechnology\":\"GPS\",\"msisdn\":\"79851620850\",\"deviceId\":\"28255923\",\"longitude\":37.62893324268332}}"
    )
})

如果你用的是Swagger 2.0： #

import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.Example;
import io.swagger.annotations.ExampleProperty;

@ApiModelProperty(value = "Сенсоры устройства", examples = @Example(
    value = @ExampleProperty(
        mediaType = "application/json",
        value = "{\"BATTERY\":67, \"VOLUME\":50, \"AIRPLANE\":false, \"ALARM\":true, \"CHARGE\":false, \"MUTE\":false, \"SCREEN\":true, \"WIFI\":true, \"LOCATION\": {\"latitude\":55.78409222171274,\"precision\":65.0,\"time\":\"2017-09-29T14:55:00Z\",\"detectionTechnology\":\"GPS\",\"msisdn\":\"79851620850\",\"deviceId\":\"28255923\",\"longitude\":37.62893324268332}}"
    )
))

这样生成的YAML里示例会被正确解析，不会多出不必要的反斜杠。

2. 配置swagger-maven-plugin关闭自动转义 #

在pom.xml里给swagger-maven-plugin添加escapeJsonExampleValues参数，阻止插件对JSON示例做额外转义：

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>1.6.2</version>
    <configuration>
        <apiSources>
            <apiSource>
                <!-- 你的其他配置，比如apiPackage、swaggerDirectory等 -->
                <escapeJsonExampleValues>false</escapeJsonExampleValues>
            </apiSource>
        </apiSources>
    </configuration>
</plugin>

3. 配置swagger-codegen-maven-plugin避免二次转义 #

转回Java代码时出现\\"这类无效序列，是因为codegen又做了一次转义。在插件配置里关闭这个行为：

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.34</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!-- 你的其他配置，比如inputSpec、language等 -->
                <configOptions>
                    <escapeExampleValue>false</escapeExampleValue>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

总结 #

核心问题就是两个插件对JSON示例的重复转义。优先用@Example注解来定义复杂示例，这是最稳妥的方式；如果不想改代码，就通过插件配置关闭自动转义，也能解决问题。

内容的提问来源于stack exchange，提问作者Roman Patrushev