Springfox/Swagger 忽略嵌套对象的 @XmlElement 注释
Springfox/Swagger ignores @XmlElement annotation for nested objects
我有以下架构。
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sampleRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="Lookup" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="accountidtgroup">
<xs:complexType>
<xs:sequence>
<xs:element name="accountIDType" type="xs:string" />
<xs:element name="accountIDValue" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="sysPlanID" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="sampleResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="Dummy" type="xs:string"/>
<xs:element name="OriginalReq">
<xs:complexType>
<xs:sequence>
<xs:element ref="sampleRequest"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
我从中生成 类 并且一切正常,除了“Lookup”元素的大小写在 Swagger UI 中被转换为小写(从技术上讲,它是对象名称)实际上应该是“查找”。如果我只是 remove/comment 取出 sampleRequest 中的“OriginalReq”元素,重建并重新启动我的应用程序,“Lookup”元素的情况在请求中显示正常。这里需要注意的重要一点是“OriginalReq”元素实际上是对“sampleRequest”元素本身的引用,这是问题的根本原因。
这是我的 pom 依赖项
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
我做了一些调查,早期版本的 springfox 在 Jaxb 注释方面存在问题,但在以后的版本中已修复。证明是响应中的“Dummy”元素出现在正确的大小写中,如果我在@XmlElement 注释中手动将其更改为其他内容,我可以看到更新的值,这意味着该注释被接受但对于 Lookup 元素它没有'不工作。因此,问题仅出现在嵌套元素具有公共元素的情况下。
有没有人运行遇到过类似的问题或者是否有解决方法?
为处于类似情况的任何人找出解决方法。
解决办法是给有问题的元素添加@JsonProperty注解。就是这样。 Swagger 将识别注释并显示正确的元素 case/name.
对于那些从 xsd 模式生成 类 的人来说,还涉及几个步骤。
- 将以下依赖项添加到您的 pom.xml 依赖项部分。
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.6</version>
</dependency>
<dependency>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics-annotate</artifactId>
<version>1.1.0</version>
</dependency>
- 在配置用于生成 类 的 maven 插件的部分下,在执行配置中,您必须再次添加上述两个依赖项和“-Xannotate”参数。它看起来像这样。
<build>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.14.0</version>
<executions>
<execution>
<id>xjc</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<schemaDirectory>${schema.src.dir}/abc</schemaDirectory>
<schemaIncludes>
<include>*.xsd</include>
</schemaIncludes>
<generatePackage>${generated.package.abc}</generatePackage>
<generateDirectory>${generated.dir}/abc</generateDirectory>
<cleanPackageDirectories>true</cleanPackageDirectories>
<bindings>
<binding>
<fileset>
<directory>${schema.binding.dir}/abc</directory>
<includes>
<include>bindings.xjb</include>
</includes>
</fileset>
</binding>
</bindings>
<extension>true</extension>
<args>
<arg>-Xannotate</arg>
</args>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics</artifactId>
<version>1.11.1</version>
</plugin>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics-annotate</artifactId>
<version>1.1.0</version>
</plugin>
<plugin>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.6</version>
</plugin>
</plugins>
</configuration>
</execution>
看看下面的参数部分和插件部分。
- 现在在您的绑定文件中,您可以使用此插件并配置冲突元素,如下所示。
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE jaxb:bindings SYSTEM "../common/resources.dtd">
<jaxb:bindings version="2.0" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:annox="http://annox.dev.java.net"
jaxb:extensionBindingPrefixes="annox">
<jaxb:bindings schemaLocation="&ApiPath;/schema.xsd">
<jaxb:bindings node="//xs:element[@name='Lookup']">
<annox:annotate target="field">@com.fasterxml.jackson.annotation.JsonProperty("Lookup")</annox:annotate>
</jaxb:bindings>
密切注意顶部配置的命名空间“annox”。
现在,如果您 运行 generate-resources,它会在您的成员变量之上创建 @JsonProperty("your element name"),swagger 将正常工作。
如果您想了解更多关于插件的信息 https://github.com/highsource/jaxb2-annotate-plugin。它是一个使用非常广泛的优秀开源软件。
对于 Springfox,我尝试使用 2.9.0 和 3.0.0 版本进行测试,但仍然是同样的问题。在我写这篇文章的时候,我认为这是 springfox 库中的一个错误,我已经在 Github 上提出了这个问题,但还没有得到回复。这是 link https://github.com/springfox/springfox/issues/3605
我有以下架构。
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sampleRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="Lookup" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="accountidtgroup">
<xs:complexType>
<xs:sequence>
<xs:element name="accountIDType" type="xs:string" />
<xs:element name="accountIDValue" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="sysPlanID" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="sampleResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="Dummy" type="xs:string"/>
<xs:element name="OriginalReq">
<xs:complexType>
<xs:sequence>
<xs:element ref="sampleRequest"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
我从中生成 类 并且一切正常,除了“Lookup”元素的大小写在 Swagger UI 中被转换为小写(从技术上讲,它是对象名称)实际上应该是“查找”。如果我只是 remove/comment 取出 sampleRequest 中的“OriginalReq”元素,重建并重新启动我的应用程序,“Lookup”元素的情况在请求中显示正常。这里需要注意的重要一点是“OriginalReq”元素实际上是对“sampleRequest”元素本身的引用,这是问题的根本原因。
这是我的 pom 依赖项
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
我做了一些调查,早期版本的 springfox 在 Jaxb 注释方面存在问题,但在以后的版本中已修复。证明是响应中的“Dummy”元素出现在正确的大小写中,如果我在@XmlElement 注释中手动将其更改为其他内容,我可以看到更新的值,这意味着该注释被接受但对于 Lookup 元素它没有'不工作。因此,问题仅出现在嵌套元素具有公共元素的情况下。
有没有人运行遇到过类似的问题或者是否有解决方法?
为处于类似情况的任何人找出解决方法。
解决办法是给有问题的元素添加@JsonProperty注解。就是这样。 Swagger 将识别注释并显示正确的元素 case/name.
对于那些从 xsd 模式生成 类 的人来说,还涉及几个步骤。
- 将以下依赖项添加到您的 pom.xml 依赖项部分。
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.6</version>
</dependency>
<dependency>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics-annotate</artifactId>
<version>1.1.0</version>
</dependency>
- 在配置用于生成 类 的 maven 插件的部分下,在执行配置中,您必须再次添加上述两个依赖项和“-Xannotate”参数。它看起来像这样。
<build>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.14.0</version>
<executions>
<execution>
<id>xjc</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<schemaDirectory>${schema.src.dir}/abc</schemaDirectory>
<schemaIncludes>
<include>*.xsd</include>
</schemaIncludes>
<generatePackage>${generated.package.abc}</generatePackage>
<generateDirectory>${generated.dir}/abc</generateDirectory>
<cleanPackageDirectories>true</cleanPackageDirectories>
<bindings>
<binding>
<fileset>
<directory>${schema.binding.dir}/abc</directory>
<includes>
<include>bindings.xjb</include>
</includes>
</fileset>
</binding>
</bindings>
<extension>true</extension>
<args>
<arg>-Xannotate</arg>
</args>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics</artifactId>
<version>1.11.1</version>
</plugin>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics-annotate</artifactId>
<version>1.1.0</version>
</plugin>
<plugin>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.6</version>
</plugin>
</plugins>
</configuration>
</execution>
看看下面的参数部分和插件部分。
- 现在在您的绑定文件中,您可以使用此插件并配置冲突元素,如下所示。
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE jaxb:bindings SYSTEM "../common/resources.dtd">
<jaxb:bindings version="2.0" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:annox="http://annox.dev.java.net"
jaxb:extensionBindingPrefixes="annox">
<jaxb:bindings schemaLocation="&ApiPath;/schema.xsd">
<jaxb:bindings node="//xs:element[@name='Lookup']">
<annox:annotate target="field">@com.fasterxml.jackson.annotation.JsonProperty("Lookup")</annox:annotate>
</jaxb:bindings>
密切注意顶部配置的命名空间“annox”。
现在,如果您 运行 generate-resources,它会在您的成员变量之上创建 @JsonProperty("your element name"),swagger 将正常工作。
如果您想了解更多关于插件的信息 https://github.com/highsource/jaxb2-annotate-plugin。它是一个使用非常广泛的优秀开源软件。 对于 Springfox,我尝试使用 2.9.0 和 3.0.0 版本进行测试,但仍然是同样的问题。在我写这篇文章的时候,我认为这是 springfox 库中的一个错误,我已经在 Github 上提出了这个问题,但还没有得到回复。这是 link https://github.com/springfox/springfox/issues/3605