Плагин JAXB Swagger - мой первый вклад в мир с открытым исходным кодом

Всем привет и добро пожаловать на мой самый первый пост на dev.to:) Я здесь уже почти год (присоединился: 24 февраля 2019, только что проверил:D) Я работаю разработчиком с 2016 года, но мне всегда нравились компьютеры и программирование, поэтому в основном после официальной работы я прихожу домой и работаю над сайд-проектом с друзьями или просто для развлечения. Мои основные интересы связаны с Java, мне нравятся как Spring, так и Java EE world, и я думаю, что #Hibernate – мой любимый сторонний фреймворк (слава мальчикам/девочкам в JBoss).

Я живу и работаю в Дебрецене, в Венгрии, это второй по величине город в стране, и здесь много возможностей для разработчиков, университет здесь для будущих разработчиков, но я предпочитаю школы, связанные с кодированием, с более практическими вещами:)

На моей последней работе мы по многим причинам предпочитали генерацию классов DTO на основе класса XSD2Java, и мы создавали приложения на основе микросервисной архитектуры и предоставляли функциональные возможности для клиентов (как внутренних (внутренние приложения), так и внешних клиентов).

Документация для этих классов и конечных точек API была обязательной, и мы экспериментировали с Swagger , в то время мы использовали фреймворк, связанный с Java EE, под названием Thorntail (он же Рой диких мух), и было очень удобно просто поместить некоторые аннотации к классам и конечным точкам API, чтобы документировать их.

Проблема заключалась в следующем:

Все наши DTO, которые были частью коммуникации, были сгенерированы с помощью maven-jaxb2-plugin и мы не смогли аннотировать наши сгенерированные классы, потому что при следующем поколении все это отправилось бы в корзину (/dev/null).

Решение: плагин JAXB2 поддерживает внешние зависимости для участия в генерации класса и мы нашли несколько вариантов продления нашей фазы генерации классов. Этот Плагин Redlab Swagger JAXB нам очень помогли но это просто помогло нам аннотировать наши поля правильными аннотациями Swagger, такими как @ApiModel и @ApiModelProperty , ничего особенного, если вы внимательнее посмотрите на эти аннотации, вы увидите, что существует множество вариантов конфигурации, таких как, атрибуты обязательные , допустимые значения , описание .

Поскольку я цитировал компанию, они перешли на спецификацию Open API , которая является более богатой спецификацией, я остался с Swagger в своих побочных проектах и на своей работе. С Swagger проблем нет, OpenAPI просто получил несколько новых способов выражения схем.

Я начал просматривать Интернет, GitHub и обнаружил, что существует множество форков упомянутого плагина JAXB, и есть один, который намного более выразителен, чем оригинальный.

Андреас-Майер-NTT/swagger-jaxb

Плагин JAXB XJC для автоматического добавления аннотаций из Swagger к сгенерированным классам из XSD

Тесты выполняются в отдельном проекте, смотрите здесь код https://github.com/redlab/swagger-jaxb-tck

ТРЕБУЕТСЯ Java 8 или выше!
создайте плагин с помощью maven
установите его в своем локальном репозитории
добавьте плагин в свой путь к классу и используйте -swaggify в командной строке jaxb или настройте его в своем pom или
добавьте репозиторий моментальных снимков sonatype в свой менеджер репозиториев. ( опубликуйте проблему, если вам действительно нужна версия dev в Maven Central )

использование с jaxb2-maven-plugin

    
                org.codehaus.mojo
                jaxb2-maven-plugin
                2.3
                
                    
                        be.redlab.jaxb
                        swagger-jaxb
                        1.5-SNAPSHOT
                    
                    
                        javax.xml.parsers
                        jaxp-api
                        1.4.5
                    
                    
                        com.sun.xml.parsers
                        jaxp-ri
                        1.4.5
                    
                    
                        com.sun.xml.bind
                        jaxb-xjc
                        2.2.11
                    
                    
                        com.sun.xml.bind
                        jaxb-core
                        2.2.11
                    
                
            
        
    
    
        
            org.codehaus.mojo
            jaxb2-maven-plugin
            2.3
            
                    
                        internal.generate
                        
                            xjc
                        
                        
                            -swaggerify
                            true
                            be.redlab.jaxb.swagger.generated.model
                            
                                ${project.basedir}/src/main/xsd/schema

Это решение решает многие мои проблемы и выполняет свою работу, но я все еще не был удовлетворен решением, поэтому я разветвил этот репозиторий и внес в него свои изменения.

Вот репозиторий с моими изменениями:

нандорхолозняк/развязность-jaxb

Плагин JAXB XJC для автоматического добавления аннотаций из Swagger к сгенерированным классам из XSD

Тесты выполняются в отдельном проекте, смотрите здесь код https://github.com/redlab/swagger-jaxb-tck

Когда вы используете XSD для создания своих классов DTO, вы можете захотеть аннотировать их, чтобы сделать их как можно более подробными для клиентов, которые будут использовать ваши конечные точки. Генерация классов XSD для Java может быть расширена с помощью этого инструмента, чтобы сделать ваши объекты API настолько декларативными, насколько это возможно. Сгенерированные классы и методы будут снабжены соответствующими аннотациями Swagger, классы с помощью @ApiModel и методы с помощью @ApiModelProperty/| .

Пример объекта XSD:

 Login object containing the e-mail and password
        
                
                    
                        
                            E-mail of the user
                        
                    
                    
                        
                            Password of the user with SHA512 encoding

Подробное README.Приведены MD и некоторые примеры, большинство функций охвачены модульными тестами, но не все, коды redlab и Andreas были немного переработаны, но не все.

В моих проектах прямо сейчас я использую Springfox для функциональности Swagger, и с помощью этого небольшого плагина детализируются все мои DTO, которые участвуют в общении с клиентами.

Если вы заинтересованы в расширенной генерации класса XSD2Java с помощью Swagger, то сейчас самое время включить эту зависимость в свой pom.xml и начните генерировать:)

Спасибо всем, кто прочитал мой первый пост в блоге, я действительно ценю это, и поскольку я действительно новичок в писательстве, я с нетерпением жду отзывов в разделе комментариев.

Мне любопытно, если кто-нибудь все еще использует схемы XSD для создания своих классов Java или, возможно, схемы JSON взяли верх (кстати, я проверяю входящий запрос на соответствие этим схемам, так что в бизнес-логике нет ничего удивительного ;))

Дайте мне знать, что вы, ребята, думаете об этом, и не стесняйтесь открывать вопросы или пиар.

Я стараюсь поддерживать код, качество кода не самое лучшее, я все еще задаюсь вопросом о множестве вариантов рефакторинга, но, знаете, его можно использовать, так как я буду использовать его с этого момента 😉

Оригинал: “https://dev.to/nandorholozsnyak/jaxb-swagger-plugin-my-first-contribution-to-the-open-source-world-1dje”