Springfox/Swagger 忽略嵌套对象的 @XmlElement 注释

Posted 2023-02-26

【中文标题】Springfox/Swagger 忽略嵌套对象的 @XmlElement 注释

【英文标题】：Springfox/Swagger ignores @XmlElement annotation for nested objects

【发布时间】：2021-01-31 12:14:44

【问题描述】：

我有以下架构。

<?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>

我从中生成类并且一切正常，除了“查找”元素的大小写在 Swagger UI 中转换为小写（从技术上讲，它是对象名称），而它实际上应该是“查找”。如果我只是删除/注释掉 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 注释方面存在问题，但在以后的版本中已修复。证明是响应中的“虚拟”元素出现在正确的情况下，如果我在 @XmlElement 注释中手动将其更改为其他内容，我可以看到更新的值，这意味着注释已得到尊重，但对于 Lookup 元素它没有不工作。所以问题只在于嵌套元素具有公共元素的情况。

之前有没有人遇到过类似的问题，或者是否有解决方法？

【参考方案1】：

为处于类似情况的任何人想出了一个解决方法。

解决方法是给有问题的元素添加@JsonProperty注解。就是这样。 Swagger 将识别注释并显示正确的元素大小写/名称。

对于那些从 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 上提出了这个问题，但还没有得到回复。这是链接https://github.com/springfox/springfox/issues/3605