JAXB Swagger插件-我对开源世界的第一项贡献

Introduction

大家好，欢迎来到我在dev.to上的第一篇文章：) 我现在已经快到这里了一年（加入：2019年2月24日，现在检查一下：D） 自2016年以来我一直是一名开发人员，但我一直很喜欢计算机和编程，因此基本上在我完成正式工作后，我就回家了，我与朋友一起进行侧项目或只是为了娱乐。 我的主要兴趣是与Java相关的主题，我喜欢Spring和Java EE世界，并且我认为#Hibernate是我最喜欢的第三方框架（对JBoss的男孩/女孩表示敬意）。

我在匈牙利的德布勒森生活和工作，这是匈牙利的第二大城市，开发人员有很多机会，大学在这里供即将到来的开发人员使用，但是我更喜欢为编码相关的学校编写实用的书:)

What did I bring to you?

在我的上一份工作中，出于很多原因，我们更倾向于基于XSD2Java类的DTO类生成，并且我们正在构建基于微服务架构的应用程序，并且为客户端（内部（内部应用程序）和外部客户端）提供功能。

The documentation for these classes and API endpoints were mandatory and we were experimenting with Swagger, at this time we were a using Java EE related framework called Ťhorntail (a.k.a Wildfly Swarm), and it came really handy to just put some annotation on the classes and API endpoints to document them.

问题如下：

• All of our DTOs, which were part of the communication, were generated by the maven-jaxb2-插件and we were not able to annotate our generated classes because on the next generation the whole stuff would go to the trash can (/dev/null).

Solution: JAXB2 plugin supports external dependencies to take part in the class generation and we found a few options to extend our class generation phase.
This Redlab 小号wagger JAXB Plugin helped us a lot but it just hepled us to annotate our fields with the proper Swagger annotations like @ApiModel and @ApiModelProperty, nothing special, if you take a closer look at these annotations you will see that there are a lot of configuration options like, the required, allowableValues, description attributes.

As I quited the company, they moved to the Open一种PI specification which is a way more rich specification, I stayed with Swagger at my side-projects and at my job.
There is no problem with Swagger, OpenAPI just got a few new ways to express schemas.

我开始在GitHub上浏览互联网，发现上面提到的JAXB插件有很多分支，并且有一个比原始插件更具表现力。

Andreas-Maier-NTT / swagger-jaxb

JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD

swagger-jaxb

JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD

Tests run in separate project, see here for the code https://github.com/redlab/swagger-jaxb-tck

Usage

• REQUIRE Java 8 or higher!
• build the plugin with maven
• install it in your local repo
• add the plugin to your classpath and use -swaggify on your jaxb command line or configure it i your pom or
• add sonatype snapshot repository to your repo manager. ( post an issue if you really want dev version in Maven Central )

use with jaxb2-maven-plugin

    <build&gt
    <pluginManagement&gt
        <plugins&gt
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>jaxb2-maven-plugin</artifactId>
                <version>2.3</version>
                <dependencies>
                    <dependency>
                        <groupId>be.redlab.jaxb</groupId>
                        <artifactId>swagger-jaxb</artifactId>
                        <version>1.5-SNAPSHOT</version>
                    </dependency>
                    <dependency>
                        <groupId>javax.xml.parsers</groupId>
                        <artifactId>jaxp-api</artifactId>
                        <version>1.4.5</version>
                    </dependency>
                    <dependency>
                        <groupId>com.sun.xml.parsers</groupId>
                        <artifactId>jaxp-ri</artifactId>
                        <version>1.4.5</version>
                    </dependency>
                    <dependency>
                        <groupId>com.sun.xml.bind</groupId>
                        <artifactId>jaxb-xjc</artifactId>
                        <version>2.2.11</version>
                    </dependency>
                    <dependency>
                        <groupId>com.sun.xml.bind</groupId>
                        <artifactId>jaxb-core</artifactId>
                        <version>2.2.11</version>
                    </dependency>
                </dependencies>
            </plugin>
        </plugins>
    </pluginManagement>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>jaxb2-maven-plugin</artifactId>
            <version>2.3</version>
            <executions>
                    <execution>
                        <id>internal.generate</id>
                        <goals>
                            <goal>xjc</goal>
                        </goals>
                        <configuration>
                            <arguments>-swaggerify</arguments>
                            <clearOutputDir>true</clearOutputDir>
                            <packageName>be.redlab.jaxb.swagger.generated.model</packageName>
                            <sources>
                                <source>${project.basedir}/src/main/xsd/schema</source>
                            </sources>
                        </configuration>
                    </execution>
            </executions>
        </plugin>
    </plugins>

…

View on GitHub

这个问题处理了我的许多担忧并完成了工作，但是我仍然对解决方案不满意，因此我分叉了这个存储库并对其进行了更改。

The contribution

这是我所做的更改的存储库：

nandorholozsnyak / swagger-jaxb

JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD

swagger-jaxb

JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD

Tests run in separate project, see here for the code https://github.com/redlab/swagger-jaxb-tck

What does it do?

When you are using XSD to generate your DTO classes you may want to annotate them to make it as detailed as possible for the clients whose are going to use your endpoints.
The XSD to Java classes generation can be extended with this tool to make your API objects as declarative as they can be.
The generated classes and methods will be annotated with the proper Swagger annotation, classes with @ApiModel and methods with @ApiModelProperty.

Example

Example XSD object:

 <xsd:complexType name="LoginRequestType"&gt
        <xsd:annotation&gt
            <xsd:documentation xml:lang="en">Login object containing the e-mail and password</xsd:documentation&gt
        </xsd:annotation>
        <xsd:complexContent>
                <xsd:sequence>
                    <xsd:element name="email" type="xsd:string">
                        <xsd:annotation>
                            <xsd:documentation xml:lang="en">E-mail of the user</xsd:documentation>
                        </xsd:annotation>
                    </xsd:element>
                    <xsd:element name="password" type="xsd:string">
                        <xsd:annotation>
                            <xsd:documentation xml:lang="en">Password of the user with SHA512 encoding</xsd:documentation>
                        </xsd:annotation>

…

View on GitHub

提供了详细的README.MD和一些示例，单元测试涵盖了大多数功能，但并非全部，redlab和Andreas的代码进行了一些重做，但并非全部。

In my projects right now I use Springfox for Swagger functionality and with this little plugin all of my DTOs which take part in the communication with the clients are detailed.

如果您对使用Swagger扩展XSD2Java类生成感兴趣，那么现在是时候将这种依赖关系引入您的pom.xml并开始生成:)

Summary

感谢所有阅读我的第一篇博客文章的人，我真的很感激，并且因为我真的很陌生，所以我希望在评论部分提供一些反馈。

我很好奇是否有人仍在使用XSD架构来生成其Java类，或者可能是JSON架构接管了（顺便说一句，我根据这些架构验证了传入的请求，因此业务逻辑并不令人惊讶；））

让我知道你们对此有何看法，并随时提出问题或公关。

我尝试维护代码，但是代码质量不是最好的，我仍然想知道重构选项的全部，但是可以知道，可以使用，因为我将从现在开始使用它;）

from: https://dev.to//nandorholozsnyak/jaxb-swagger-plugin-my-first-contribution-to-the-open-source-world-1dje