Как просмотреть документацию xsd: в HTML-разметке?

Question

Я создаю WSDL / XSD для служб SOAP из модели UML с использованием IBM Rational Software Architect (RSA). RSA позволяет документировать классы и атрибуты в модели с использованием расширенного форматирования.

Например, у меня есть следующая документация по классу Трейлер :

Колесный Автомобиль , предназначенный для буксировки другим лицом. Автомобиль . Известные подтипы включают в себя:

• Караван
• BoxTrailer
• BoatTrailer

Когда модель UML преобразуется в WSDL / XSD (с использованием готового преобразования UML в WSDL), форматирование сохраняется как разметка HTML внутри элемента xsd: documentation:

  <xsd:complexType name="Trailer">
    <xsd:annotation>
      <xsd:documentation>&lt;p&gt;
    A&amp;nbsp;wheeled &lt;strong&gt;Vehicle&lt;/strong&gt; that is designed for&amp;nbsp;towing by another &lt;strong&gt;Vehicle.&lt;/strong&gt; Known
    subtypes include:&amp;nbsp;
&lt;/p&gt;
&lt;ul&gt;
    &lt;li&gt;
        &lt;strong&gt;Caravan&lt;/strong&gt;
    &lt;/li&gt;
    &lt;li&gt;
        &lt;strong&gt;BoxTrailer&lt;/strong&gt;
    &lt;/li&gt;
    &lt;li&gt;
        &lt;strong&gt;BoatTrailer&lt;/strong&gt;
    &lt;/li&gt;
&lt;/ul&gt;</xsd:documentation>
    </xsd:annotation>
  </xsd:complexType>

К сожалению, это действительно трудно читать, и я искал (без удачи) программу, которая может просматривать WSDL / XSD с документацией в разметке HTML.

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

Я написал шаблон JET, который извлек документацию из модели и вывел ее в HTML, и я, вероятно, мог бы написать некоторый XSLT для выполнения чего-то похожего из XSD, но я надеялся, что есть программа (в идеале бесплатная), которая может просматривать документацию в формате HTML.

По сути, я бы хотел сказать пользователям нашего веб-сервиса, что они могут просматривать программу WSDL in X, если они хотят прочитать документацию - кто-нибудь знает лучшее решение для этого?

Edit: Спасибо за предложения, но я думаю, что у меня есть решение! Я не осознавал, что RSA может экспортировать WSDL в HTML (щелкните правой кнопкой мыши на WSDL, экспорт, HTML). Сгенерированный HTML-код имеет графическое представление каждого элемента схемы, документацию для каждого элемента, а также исходный источник, и все они связаны друг с другом гиперссылками.

Самое главное, документация снова отформатирована! Небольшое предостережение заключается в том, что ;nbsp появляются в выводе HTML. Похоже, это связано с тем, что амперсанд экранирован в HTML:

 

Вместо этого должно быть

 

Я обновлю свое преобразование модель-модель, чтобы обеспечить замену ;nbsp на реальные пробелы (я не верю, что в документации мне понадобятся неразрывные пробелы), поэтому сгенерированный WSDL / XSD никогда их не получит.

Answer 1

Эта проблема исправлена ​​ в RSA 8.0.4 - теперь она поддерживает экспорт в WSDL / XSD с простым текстом (а также возможность сортировки схемы по типу, а затем по алфавиту!).

Чтобы просмотреть документацию в WSDL / XSD, сгенерированную из модели UML в предыдущих версиях RSA, самым простым решением является экспорт WSDL / XSD в виде HTML с использованием RSA.Вы можете сделать это, щелкнув правой кнопкой мыши на WSDL / XSD, выбрав экспорт, затем выбрав HTML.

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

Самое главное, документация (это практически не читается в WSDL / XSD) снова богато отформатирован!Небольшое предостережение заключается в том, что ;nbsp, которые вставляет редактор документации RSA, также появляются в выводе HTML.Похоже, это происходит потому, что амперсанд не только экранируется в WSDL / XSD (что хорошо), но и в HTML (плохо!):

 

Вместо этого он долженbe

 

Простой обходной путь - заменить все   в WSDL / XSD реальными пробелами перед генерацией HTML.

Answer 2

Тип <xs:documentation> - <xs:any>, поэтому вы должны иметь возможность включать документацию, не экранируя разметку, при условии, что это правильно сформированный фрагмент XHTML вместо HTML. Я предполагаю, что некоторые инструменты XML-схемы смогут интерпретировать встроенный XHTML и отображать его как форматированный текст.

Обратите внимание, что если разметка не экранирована, это обязательно должен быть правильно отформатированный фрагмент XML, иначе элемент документации приведет к неправильной схеме. Это относится и к HTML-сущностям! Если документация содержит (неэкранированную) ссылку на сущность (кроме 5 предварительно определенных сущностей XML), то ваша схема либо должна содержать внешнюю ссылку DTD, либо иметь встроенный DTD, определяющий, что является текстом замены этого лица. В вашем случае документация содержит ссылку на сущность  . Вероятно, проще всего будет заменить такие объекты соответствующими символами / текстом Unicode или ссылками на символы (используйте   для  )

Если у вас есть шанс, попробуйте включить документацию без разметки и убедитесь, что она будет правильно оформлена. В противном случае вам, вероятно, потребуется обработать документацию дважды: 1) разобрать схему и извлечь документацию 2) снова проанализировать текст документации (возможно, в виде HTML, а не XML).

Answer 3

Я пробовал это с последней сборкой QTAssistant, и это отображается только в справочной панели схемы;Я поместил запрос функции для вида сетки, а также генератор документации, чтобы работать так же.Это то, что вы ожидаете?

На панели справки отображается аннотация объекта схемы, выбранного в представлении «График / диаграмма».Для отображения панели справки нажмите F1.

Answer 4

Я очень сомневаюсь, что стандартные редакторы xml / xsd могут интерпретировать теги html и генерировать соответствующую документацию. Oxygen XML Editor делает хорошую работу по пониманию и преобразованию сущностей XML (например,