Самодокументируемый Jax-Ws С Поддержкой Ограничений Xsd.

В этой статье я расскажу о создании самодокументируемого веб-сервиса (jax-ws), использующего элементы ограничений XSD.

Описание задачи

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

например, вся информация о структуре таблиц хранится в одном формате (это может быть файл любого подходящего или собственного формата), а на его основе — сами таблицы, документация по этим таблицам и объекты DAO для работы с ними.

создаются таблицы.

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

Минусы в том, что все желающие должны иметь возможность редактировать этот файл и должны быть конвертеры в нужные форматы.

В веб-сервисах эти концепции называются «сначала контракт» и «сначала контракт».

Сначала контракт — когда wsdl создается впервые и на его основе генерируется код Java. Контракт последним — наоборот, сначала код Java, а потом wsdl. О плюсах и минусах можно прочитать по следующим ссылкам: docs.spring.io/spring-ws/sites/1.5/reference/html/why-contract-first.html stackoverflow.com/questions/763827/what-is-the-better-approach-to-web-services-contract-first-or-contract-last В этой статье я рассмотрю создание веб-службы SOAP с самодокументацией, чтобы получить аналогичное решение — вся информация о веб-службах будет содержаться в ней самой.

Получается своеобразный «контракт последний» — сначала пишется код, а затем из него получается документация в виде wsdl, которая содержит как можно больше информации об этом веб-сервисе — комментарии ко всем методам и типы, с которыми работает сервис и большая часть логики проверки правильности данных.

Почему это решение может быть полезным? В том случае, когда вся разработка сосредоточена на написании кода и на его основе генерируется wsdl, а не наоборот. Или когда сложно изначально содержать документацию в wsdl. Но если веб-методы написаны на основе аналитики, то хранить эту аналитику лучше в wsdl. Те.

сначала wsdl, а из него генерируются методы, классы и читаемая документация.

В противном случае возникнут проблемы с проверкой соответствия уже написанного сервиса тем.

задача.

Корректность входных данных также лучше проверять на стороне xsd, чтобы можно было проверить запрос без подключения к веб-сервису и чтобы эта логика была видна (в xsd), а не зашита где-то в недрах обслуживание.

Варианты решения

В частности, apache CXF (jax-ws) предоставляет аннотацию WSDLDocumentation, которая применяется к веб-методам и задает описание веб-метода, которое впоследствии попадет в wsdl. Для документирования сущностей XML, которые будут использоваться в веб-методах, используется библиотека jaxb-facets ( dsg.tuwien.ac.at/staff/hummer/tools/jaxb-facets.html , github.com/whummer/jaxb-facets ).

Он позволяет, как и CXF для веб-методов, документировать классы и поля XML-компонентов.

В дополнение к этому добавлена поддержка XSD Restrictions — дополнительных ограничений на значения полей xml. (описание ограничений XSD находится здесь www.w3schools.com/schema/schema_facets.asp ) Это будет полезно, когда вам нужна логика проверки правильности значений, более сложная, чем обязательная/необязательная — потому что jaxb не полностью поддерживает возможности проверки xsd. В частности, можно будет указывать ограничения на минимальное и максимальное значения, использовать регулярные выражения, использовать различные методы обработки строк для пустых значений, устанавливать ограничения на длину значения.

Выполнение

В статье я опишу конкретные примеры с кусочками кода.

Полный сервис можно скачать по этой ссылке.

dl.dropboxusercontent.com/u/7519092/jax-ws-example.zip Это проект Maven IDEA. В IDEA вы можете открыть его, импортировав проект IDEA или импортировав проект maven. Pom.xml настроен на генерацию файла wsdl и преобразование его в html с помощью xslt, но, к сожалению, этот wsdl не содержит тега документации из jaxb-facets, хотя в сгенерированном wsdl (доступен по ссылке /web_service/Веб-сервис? wsdl) этот тег существует. Использование аннотаций в проекте тоже разное — там аннотации применяются для получения методов, а в этих примерах к полям классов.

Это сделано для того, чтобы сократить статью.

Чтобы применить аннотации к полям класса, необходимо либо не использовать методы get, либо указать @XmlAccessorType(XmlAccessType.FIELD).

Примеры

Ограничение на максимальное и минимальное значения даты и времени.

   

 @XmlSchemaType(name = "date")
 @Facets(minInclusive = "1900-01-01", maxInclusive = "9999-12-31Z")
 Date date;
 

   

• Visibility.net Выбран Системами Контроля Инцидентов

  19 Oct, 24

• Гравитация (Гравитация)

  19 Oct, 24

• Клинки Хаоса И Оскорбления: 5 Примеров Виртуального Оружия, Сделавшего Игру Интереснее

  19 Oct, 24

• Сервис По Заказу Уборки Квартир Qlean Вышел На Рынок Санкт-Петербурга

  19 Oct, 24

• Ansible Dynamic Inventory От Dns Или Как Тратить Время На Поиск Стандартов

  19 Oct, 24

• Контекст Категории

  19 Oct, 24

• Исходный Код → Краш!

  19 Oct, 24

• Отладка Приложения Angular Cli В Vscode С Использованием Предварительного Просмотра В Браузере

  19 Oct, 24

• Юнеско: Спамеры Не Крадут Базы Данных У Почтовиков

  19 Oct, 24

• Компонент Для Подсветки Кода В Текстах Блогов, На Форумах И Т.п.

  19 Oct, 24